ClearHead Specifications
This is intended to be a space where key specifications can live, separated by the implementation details of the underlying projects.
This enables those who wish to build upon the specifications, but avoid the tooling to do such without needing to carve out the relevant pieces from the implementation products.
Scope and Source of Truth
The specifications/ directory is implementation agnostic. It defines behavior and contracts that any conforming implementation can follow, regardless of language, runtime, storage engine, or framework.
To avoid duplication and drift:
ontology/is the source of truth for ontology artifacts (terms, shapes, JSON-LD context/schema, and ontology-out contracts).specifications/is the source of truth for platform-level interpretation and conformance guidance (how downstream tools should apply those ontology artifacts).- Implementation repositories (for example CLI or core libraries) are expected to document only implementation mechanics, and should reference these specifications for normative behavior.
Releases
The specifications are released together under one semantic version, tagged vMAJOR.MINOR.PATCH; CHANGELOG.md records what each release changed. While the major version is 0, any release may change the contract.
An implementation conforms to a release, never to a branch. Every schema’s $id names the release it belongs to:
https://clearhead.dev/schemas/<tag>/<name>.schema.json
and a document declares the schema it follows with that URL as its $schema. A release is one commit that moves every $id to the new tag and gives the changelog’s pending entries that version; the tag points at that commit.
clearhead.dev is this specification as a site, published from the release branch (platform Decision 49): a release is tagged on main, release is fast-forwarded to it, and the site, the application vocabulary (https://clearhead.dev/vocab/app/v1#) and the schemas update together. Releases before v0.2.0 named their schemas by their raw.githubusercontent.com URL, which still resolves.
ClearHead Platform Overview
Many of these other specifications cover rather precise technical details, but i want to take a bit of time to cover the overarch process that is guiding much of these specifications as a way to bring meaning to the disperate parts.
The Problem Being Solved
At its core, ClearHead is an attempt to express intention in a clean, straightforward manner.
This starts as a simple text file on your machine, your replacement for todo.txt. However, as your needs grow, the tools will grow with you at the pace you need, rather than forcing you into a complex system from the start.
When you do start integrating these into your systems, it is important that these intentions become just as much data as they are text, and we will have access to the tools that power users are used to, rather than reinventing the wheel again.
We have demanding lives, and making these intentions useful takes more work than one might think when they start their todo.txt, and the goal is to allow people to use these intentions in whatever way makes sense within their system to:
- Keep track of what they need to do
- both at home and while travelling
- with or without internet access
- on or off their home devices
- Pass intentions to other agents
- coworkers
- family members
- hired professionals
- LLM agents
- Analyze and reflect on their intentions
- Capture data on how they spend their time
- Reflect on what they have accomplished
- find the dependencies between intentions
- Integrate this with other data
- Calendar events to track intentions
- Links to appropriate resources
- Automations to help accomplish intentions
- using the intentions themselves as a workflow engine for both humans and machines
Values and Principles
With this platform, my goal is to create a system with a few core values:
-
local-first: Users should be able to use the system fully offline, with optional cloud sync.
- Adherence to Standards: In particular, i believe we achieve local-first software through the coordination of standards and data rather than bespoke implementations.
- Interoperability: Different tools and implementations should be able to work together seamlessly.
- This is why these specifications exist as a separate repo, so that other implementors can build their own tools that interoperate with the ecosystem.
-
Incremental Adoption: Users should be able to start small and gradually integrate more features as they see fit, or not! A core usecase is the single person, writing a plaintext file in the woods are their phone without internet.
- This is why the string file format is the core of the system, and everything else builds on top of that.
- Power users will also need to extend the system beyond the core and this needs to be possible without breaking the core usecases.
-
Opinionated Defaults: Everything from the file format to the tools is built with intention. We want to leverage best practices to make a nice experience out-of-the-box rather than making people build their workflow from scratch.
- While we want to make customizability core, preferrably, for most this is a rare occasion and they can be productive with the system before they need to adopt the entire workflow
These values are some of the big reasons i have not used one of the leading task frameworks as i didnt feel that any of them held to all of these values even if they stuck to one or two.
Design principles
Three rules that kept deciding designs (the agent sandbox, Decisions 36, 55 and the template binding) before anyone wrote them down:
- Standards at the boundary, our model at the core. Adopt a standard inside the core when it models the same concept the domain does (RFC 5545’s reading of local time, ISO 8601 intervals). When it models a neighbouring concept (VTODO’s assignable task beside an action’s intent), project the subset it can carry and say what is lost; never let it share authority over the model.
- Ownership is not storage. Who may change a fact and where its bytes live are separate questions. A fact ClearHead owns can travel inside another format (an
X-CLEARHEAD-*property) when that keeps it with the thing it describes. - Proposals are evidence; only the human’s act makes them authority. An inference, a planner’s output, a title that matches a template or a change made on another device may be surfaced for acceptance. None becomes durable intent until a person accepts it.
Philisophical Inspirations
This has been a topic of research of mine for many years and it would be rude of me not to credit many of these authors for guiding and shaping my thinking on the topic:
- Getting Things Done by David Allen - The foundational text on modern task management and productivity.
- Ive been practicing GTD personally for over a decade now and it shapes much of my thinking on these topics. In terms of clear, pragmatic systems for intentions I believe David does the best at creating a system that is empathetic to how humans actually work.
- Deep Work by Cal Newport - A deep dive into the importance of focused work and how to achieve it in a distracted world.
- While GTD is a brillient set of systems, it has relatively little to say on WHAT actions you should take and WHEN and how to go about them. Deep work answers this question by arguing that we should be trying to do as much deep work as possible, minimizing and automating shallow work.
- Cal has done a great job of outlining how professions like programming need to work and serves as a good guide to finding focus in a world of distractions.
- The Agile Manifesto by Kent Beck et al. - A set of principles for software development that emphasizes collaboration, flexibility, and customer satisfaction.
- While mostly focused on software, i believe the core insight of agile is a sense of humility and pragmatism when it comes to delivering work. Whereas the first two are about optimizations, agile is this funny instance of a more humanistic perspective peaking out from a very corporate mindset.
- Marie Kondo’s life-changing magic of tidying up by Marie Kondo - A guide to decluttering and organizing your physical space to create a more joyful life.
- Marie does a good job of making a cleaning book not about cleaning, a productivity book not about productivity. Instead, or in addition to her wonderful cleaning tips, she subtly influences the reader with zen buddhist principles of mindfulness and intentionality, and serves as one of the more subtle pieces in this list but no doubt one of the most sophisticated in terms of the topics she covers
- Atomic Habits by James Clear - A comprehensive guide to building good habits and breaking bad ones through small, incremental changes.
- Another area that GTD doesnt cover as throughly is the idea of habits. or put another way, habits can be seen as a higher level system for managing actions that recur frequently. James does a great job of breaking down the science of habits and giving practical advice on how to build and maintain them.
- I see it as using the systems of GTD to create the habits we want to see for ourselves, first with technical tools, until they become second nature.
Technical Inspirations
Over the years of research I have seen many implementations that have inspired this work:
- todoist - A powerful task management system with a strong focus on user experience and cross-platform support.
- My current personal task system while this system is built and while it adheres to most of the web 2.0 principles, it does a good job of being a solid, reliable task manager that just works and any system that replaces it will need to meet this high bar for both usability and reliability.
- (Neo)vim - An extensible and highly customizable text editor that serves as the foundation for many ClearHead tools.
- as my personal editor, neovim is a constant source of inspiration from both a technical perspective, as well as a user experience perspective. this tool will in many ways try to bring some of the same principles of extensibility and customizability to task management that neovim brings to text editing.
- todo.txt - A simple, plaintext-based task management system that emphasizes simplicity and portability.
- has always been the standard bearer of simplicity in task management and while it lacks many of the advanced features of modern systems, its simplicity and portability are unmatched. ClearHead aims to aknowledge this core insight that one should always be able to go back to editing a file to list out intentions even if we grow from there.
- taskwarrior - A command-line task management tool that offers advanced features and flexibility for power users.
- taskwarrior shows in many ways the opposite virtue of todo.txt, in that it wants to leverage the power of data to do really cool things with relatively little effort. This is another very good virtue that clearhead will seek to embody.
- org-mode - An Emacs-based system for organizing tasks, notes, and projects with a focus on plain text and extensibility.
- org-mode is another very powerful system that has a strong focus on plain text and shows that there is no reason a plain-text based system cant be as powerful as a database-backed system. While i personally dont use emacs, i do admire the power and flexibility of org-mode and its community.
While all of these systems have their strengths and weaknesses, none of them fully embody the values and principles that ClearHead aims to achieve, and thus i felt there was a need for a new system that could bring these ideas together in a cohesive manner.
Index
Here is the index of specifications and their purpose within the whole:
- Process Overview - The most abstract overview of the process which outlines the key steps in a way that is implementation agnostic.
- This document serves as the high-level guide for how different tools should approach the handling of action files and user intentions, ensuring a consistent experience across the ecosystem.
- Action File Format - The format for
.actionsfiles that represent actions (execution records). If you read nothing else, start here to understand how actions are defined.- For Example, while tree-sitter-actions implements this specification using tree-sitter, it could just as easily be implemented using PEGS or any other parsing technology.
- iCalendar VTODO Projection Specification - Defines recurring Plan VTODOs, standalone Action VTODOs, expansion, identity, and bidirectional vdir synchronization.
- Workspace - The structure, discovery, and identity conventions for workspaces within the ClearHead ecosystem. This allows different tools to interoperate without confusion as they can leverage shared configuration, naming semantics, and structure to build more interesting systems
- Both clearhead-cli and clearhead.nvim implement these conventions to manage collections of actions, wether they be plaintext files, json data, or full databases.
- Configuration - Defines how ClearHead implementations handle configuration, including XDG directory structure, JSON configuration format, layered configuration (defaults → file → env → args), and extension mechanisms for implementation-specific settings. This ensures all tools share a common configuration approach while allowing for tool-specific extensions.
- Implementations like clearhead-cli and clearhead.nvim can share configuration via
~/.config/clearhead/config.jsonwhile maintaining their own sections for tool-specific settings.
- Implementations like clearhead-cli and clearhead.nvim can share configuration via
- Action JSON Schema - The canonical JSON projection shape for action data. It supports interchange and validation without replacing the plaintext workspace as durable authority.
- Implementations may export this projection for pipelines and external analysis; synchronization back into workspace source requires an explicit mutation contract rather than treating JSON as a second write model.
- Charter JSON Schema - The canonical JSON projection shape for charter documents, following the same projection rules as actions. It carries charter facts only; Actions and Plans join back through their charter reference.
- Ontology & Linked Data - How a workspace is published as RDF: the application graph (
app:) queries read, field by field, and its meaning in the ClearHead ontology’s standard terms (CCO and IAO); graph identity, conformance and determinism.- This specification ensures that while tools typically interact with simple JSON, the data remains semantically rigorous and interoperable with the broader Semantic Web (RDF/JSON-LD).
License
Released under the MIT License: use it, implement it, build on it, commercially or not. The ontology imports keep their own licenses: ontology/imports/cco-v2.2.ttl is the Common Core Ontologies, BSD 3-Clause, © CUBRC, Inc.; ontology/imports/iao-2026-03-30-module.owl is a module of the Information Artifact Ontology, CC BY 4.0.
Action file format
title: actions file specification description: File specification for actions in .actions files author: primary_desktop categories: Reference created: 2025-01-19T03:16:49-0800 updated: 2026-04-20T00:00:00-0800 version: 2.0.0
This specification defines the *.actions format.
File roles are defined in Workspace; entity roles are defined in Ontology.
Scope and Principles
.actionsis a plaintext interface for actions.- It must remain easy to read and write by hand.
- Parsers should be whitespace-tolerant and symbol-driven.
- The format should remain backwards-parseable over time.
Parser Guidance
Special characters
Reserved characters must be escaped with \ in freeform fields unless otherwise noted.
Canonical property order (recommended for formatters and linters):
[]state marker=alias$description block~sequential-children marker!priority*objective/parent reference+context tag@do date/time, followed byR:recurrence:due date/time^created date/time%completed date/time#identifier<predecessor reference>child depth marker
Reference styles
References are resolved in workspace scope and may be represented as:
- Full UUID (
01951111-cfa6-718d-b303-d7107f4005b3) - Short UUID prefix (
01951111) - Alias (
staging-deploy) - Name (
Wash clothes)
Resolution order:
- Full UUID match
- Short UUID prefix match
- Alias match (case-insensitive)
- Name match (case-insensitive)
Unresolved references should produce lint warnings.
Date and Time
Dates/times should follow ISO 8601-compatible formats.
Supported date forms:
YYYY-MM-DDYYYYMMDD
Supported time forms:
hh:mm:ss.sss/hhmmss.ssshh:mm:ss/hhmmsshh:mm/hhmmhh
Timezones are optional; local time is assumed when omitted. Offsets and Z are allowed.
A time is kept as written: one without an offset is local time in the viewer’s
zone and is written back without one, and one with an offset keeps it, so a file
never changes with the machine that formats it (Decision 52). A local time
resolves as RFC 5545 resolves one (§3.3.5): when it occurs twice, as clocks go
back, it is the first occurrence; when it does not occur, as clocks go forward,
it is read with the offset in effect before the gap, so 02:30 on the night
clocks jump from 02:00 to 03:00 is 03:30.
A date covers its whole day. A date and time is an instant, however precisely it
is written: T17:00 and T17:00:00 are the same instant. A range start/end is
half-open: it begins at the start’s first instant and ends where the end does, a
date’s following midnight or a time itself. @ and : read dates, times and
ranges the same way (Decisions 47 and 51).
Field Semantics
Depth (required for children)
Children start with one or more > markers. Whitespace indentation is presentation only and should not affect parsing.
State (required)
[ ]not started[x]completed[-]in progress[=]blocked/awaiting[_]cancelled
Name (required)
Primary human-readable label for the action.
Description (optional)
Description blocks begin and end with a line that starts with $:
[ ] Weekly review
$ Review commitments and update priorities.
include links like [[agenda|https://example.com/agenda]] when needed.
$
Links (optional inline)
Wiki-style links are supported in names and descriptions:
[[text|url]][[url]]
Escape literal link tokens with \[\[, \]\], and \|. Because [ may begin a link, a literal standalone opening bracket in a description must also be escaped as \[; an unescaped lone [ is a parser-integrity error rather than prose that tools may reinterpret.
Links may span syntactically insignificant whitespace, including newlines. An unescaped [ inside link content is reserved as a structural synchronization point: when a closing ]] is missing, it lets Tree-sitter insert a MISSING close before the next action’s [state] marker rather than consuming that action. The recovered link remains available for diagnostics, but the document is not eligible for formatting or semantic mutation until fixed.
Priority (optional)
!<number> where lower numbers are higher urgency by convention.
Parent / Objective reference (optional)
*<reference> links a root act to an objective or higher-level grouping. Objective path notation is allowed, for example: *work/clearhead/docs.
Context tags (optional)
Contexts are designated by + tags. The canonical form is a single + group with comma-separated tags, which is what formatters emit:
[ ] Prepare deck +work,meeting,client
The space-separated form is also accepted and parsed losslessly — every + group is collected, not just the last:
[ ] Prepare deck +work +meeting +client
Parsers must collect tags from all context nodes; keeping only the final group is silent data loss (see DECISIONS.md Decision 33). Tag hierarchies are configured in configuration.md.
Alias (optional)
Aliases provide stable references independent of name changes:
[ ] Deploy staging build =staging-deploy
Sequential children (optional)
~ on a parent means direct children are implicitly sequential.
Predecessors (optional)
<ref> denotes logical dependencies that must be closed before this act is dependency-clean.
Do date/time (optional)
@ is intent: when the Action is planned to be worked. It bounds nothing; the
Action may be worked before or after it. It takes one of two forms:
@<datetime>: the planned start. A date alone plans the whole day, as an all-day event; a date and time plans a point.@<datetime>/<datetime>: an ISO 8601 interval, a planned block. Only the fullstart/endform is valid, as for:.
The block is read as any range is (Date and Time), as a
calendar reads one: @2026-10-03T09:00/2026-10-03T09:30 is thirty minutes and
@2026-10-03/2026-10-05 is three whole days.
Duration is never written; it is the length of the @ block. Earlier files
wrote it as D<minutes> after @ (@2026-10-03T09:00 D15); parsers should
keep reading that form, and formatters write it as the equivalent block
(@2026-10-03T09:00/2026-10-03T09:15). A D after a date-only @ has no
equivalent block; it is dropped, and the whole day stays planned.
Due date/time (optional)
: is the Action’s window: when it can and must be done. It takes one of two
forms:
:<datetime>: a deadline only.:<datetime>/<datetime>: an ISO 8601 interval, a lower bound (“not before”) and a deadline. Only this fullstart/endform is valid: no ISO 8601 durations and no abbreviated end.
The window is read as any range is (Date and Time): it opens
at its lower bound, and the Action is late from where its deadline ends. So
:2026-10-05 is late from 2026-10-06T00:00, and :2026-10-05T17:00 is late
from 17:00.
Action hierarchy composes windows without changing the locally stored values.
An Action’s effective window opens at the latest lower bound asserted by itself
or any ancestor and closes at the earliest deadline asserted by itself or any
ancestor. A missing bound therefore inherits an ancestor’s naturally, while a
child may narrow the inherited window. @ is not inherited.
Coherence:
- A planned block outside the effective window is a warning:
@starting before the window opens, or its block ending after it closes. - A local window bound outside an ancestor’s window is a warning.
- An empty effective window, which opens at or after it closes, is a violation,
as is an
@block that ends at or before it starts.
Queries use the effective window, but tools must not write inherited bounds into source unless the user explicitly requests a materializing operation.
Work that can happen outside an Action’s window, such as preparing before it
opens, belongs in its own Action with its own window, related by < where
order matters.
Recurrence
R: followed by an RFC 5545 §3.3.10 RRULE value may follow the complete @ block it repeats. The block’s start supplies DTSTART. For example:
[ ] Weekly review @2026-10-26T08:00/2026-10-26T12:00 R:FREQ=WEEKLY;BYDAY=MO :2026-10-26T17:00
FREQ is required. Standard rule parts (INTERVAL, COUNT, UNTIL, BYDAY, etc.) retain RFC 5545 semantics, including its value types and the mutual exclusion of COUNT and UNTIL. The rule is text, not a new recurrence language. Approved examples live in examples/actions/habits/.
Which files give R: meaning is defined in Workspace, with semantic diagnostics in Linting. Habit generation, template stamping and occurrence windows are defined in Process.
Completed date/time (optional)
%<datetime> records completion timestamp.
Created date/time (optional)
^<datetime> records creation timestamp.
If missing, tooling may derive this from UUIDv7 timestamp data when present.
Identifier (optional)
#<uuid> stores a stable identifier.
- Ad-hoc/manual acts typically use UUIDv7.
- Habit occurrences use deterministic UUIDv5 based on the native Habit UUID and canonical slot; steps also use the stable template-step UUID (see ics_schedule_spec.md).
Examples
Examples are in examples/README.md.
Formatting
title: Actions File Formatting Specification description: Canonical formatting rules for .actions files author: primary_desktop categories: Reference created: 2026-01-01 version: 3.2.0
Actions File Formatting Specification
This document covers the formatting rules for .actions files in the ClearHead ecosystem. The goal of this specification is to ensure consistent and readable formatting across different tools and editors while respecting the syntactically insignificant nature of whitespace in the ClearHead file format.
Source integrity gate
Formatting existing source requires a clean parser-integrity result. A tree containing Tree-sitter ERROR/MISSING nodes or an explicit named recovery node is useful for diagnostics, but it is not safe to reserialize: recovered fields, hierarchy, or UUIDs may be attached to the wrong action. The formatter must return no output/edit until those issues are fixed. This applies to stdout as well as in-place and LSP formatting because stdout may be redirected over the source file.
This is not a dependency on semantic lint policy. Parser integrity is a shared fact: the linter renders it as an error and may offer a surgical code action; the formatter only enforces the clean-source capability. Warnings or semantic errors that do not threaten source fidelity do not block formatting.
Rules
New Actions on New Lines
While actions themselves may also contain newlines, it is recommended that each action be placed on its own line to enhance readability.
Input:
[ ] Task 1[ ] Task 2[ ] Task 3
Output:
[ ] Task 1
[ ] Task 2
[ ] Task 3
This makes each action clearly distinguishable and easier to read.
Indentation for child actions
Child actions should be indented to reflect their hierarchy within the action list. Each level of depth should be represented by either 2 spaces or a tab character, depending on the user’s preference.
[ ] Parent Task
[ ] Child Task 1
[ ] Sub-child Task
[ ] Child Task 2
Metadata Spacing
The formatter enforces exactly one space at every boundary between distinct fields:
- Space after state brackets:
[x] Taskrather than[x]Task - Space before each metadata field:
Task !1 +tag #idrather thanTask!1+tag#id
It does not add a space between a field’s own icon and its value: !1, #id, *StoryName stay compact. Only the boundary between fields is owned by the formatter; the inside of a field is not.
This is enforced at two levels, and both matter for idempotency:
- The grammar (
tree-sitter-actions/patterns.js) never lets a text-bearing token (name, description text, story, tags, predecessor names) absorb a leading or trailing whitespace run into its own byte range – interior spaces (multi-word names) are untouched, but the space right before the next sigil, or on either side of a link, is never silently swallowed into the preceding token. - The Topiary query (
queries/actions/formatting.scm) then unconditionally prepends one space at everyname/metadatafield boundary.
Because no token can absorb the boundary space itself, the two never compete, and format(format(x)) == format(x) for spacing.
Description paragraphs
Whitespace inside a $...$ description belongs to the description, not to the
formatter. Formatters must preserve interior spaces and newlines verbatim,
including blank lines between paragraphs. They may normalize only the boundary
between the description field and neighboring fields.
[ ] Record outcome $first paragraph.
second paragraph.$ !2
Parsing, formatting, and mutation must round-trip the description above as
"first paragraph.\n\nsecond paragraph."; silently deleting or replacing its
newlines is data loss.
Line endings
The formatter writes LF line endings. Formatting makes a file regular, so a CRLF file comes back as LF; this is a change of form, not data loss. Anyone who wants to keep CRLF can turn formatting off. Edits that do not reformat a file, such as stamping a charter ID, keep the file’s existing line endings.
Version History
3.2.0 (2026-10-13)
- Line endings: the formatter writes LF; edits that do not reformat a file keep its existing line endings.
3.1.2 (2026-09-22)
- Description content is a formatter leaf: interior newlines and blank lines are preserved verbatim instead of being discarded as grammar extras.
3.1.1 (2026-07-05)
description_textis now trimmed like the other freeform tokens. Previously it swallowed the spaces around links inside a$...$block, so topiary’s reconstructed spacing stacked on top and produced a non-idempotent double space (text [[link]] text) that failed topiary’s idempotence check. Descriptions now hug their$markers ($text$, icon->value compact) and links inside get a single owned space on each side.
3.1.0 (2026-07-03)
- Breaking: Formatter now enforces horizontal spacing at field boundaries (reverses the 2.1.0 decision to leave this to lint-only)
- Root cause of the earlier inconsistent double-spacing:
notChars()-based grammar tokens (name, story, tags, predecessor names) greedily absorbed boundary whitespace into their own byte range, so a topiary@prepend_spacedirective could double up with whitespace already baked into the preceding token - Fixed at the grammar level with
notCharsTrimmed(), which never lets a token start or end on whitespace while still allowing interior spaces formatting.scmnow uses two blanket rules covering state->name and every field->field boundary- Icon->value spacing within a single field (
!1,#id) remains unenforced/compact – unchanged from prior versions
3.0.0 (2026-01-31)
- Breaking: Formatter now enforces indentation based on action depth
- Depth markers themselves are indented (not just action content)
- Indentation respects user preferences (spaces vs tabs, width)
- Updated Topiary query to add indentation rules
- Updated Neovim indents.scm to match Topiary behavior
Migration: Run clearhead format --in-place on existing files to update formatting
2.3.0 (2026-01-30)
- expanded to include guidance on the various formats
2.1.0 (2026-01-18)
- Breaking: Reduced scope to vertical spacing only
- Removed horizontal spacing enforcement (whitespace-insensitive by design)
- Removed indentation enforcement (depth markers define hierarchy)
- Formatter now implemented as Topiary query in tree-sitter-actions
- Dramatically simplified specification
2.0.0 (2026-01-18)
- Removed list style
- Removed metadata ordering from formatter scope
1.1.0 (2026-01-03)
- Expanded scope to all spacing
1.0.0 (2026-01-01)
- Initial specification
Linting
title: Actions File Linting Specification description: Optional checks for correctness, consistency, and best practices in .actions files author: backup-admin categories: Reference created: 2026-01-03 version: 1.1.0
Actions File Linting Specification
This specification defines optional linting rules for .actions files. While the Action File Format defines valid syntax and Formatting handles presentation (spacing, indentation), this document defines semantic quality checks that detect correctness issues, temporal problems, and style violations.
Philosophy
This specification defines a relaxed parser, strict linter approach:
- Relaxed parser: Accepts most valid input into a parse tree structure. Even minor issues produce a parseable tree rather than parse errors.
- Strict linter: Performs rigorous checking of the parsed tree for correctness, consistency, and best practices.
This approach aligns with modern tooling like TypeScript, where the parser is permissive and the typechecker/linter provides strict validation.
Parser recovery is diagnostic input, not semantic authorization. Tree-sitter ERROR/MISSING nodes and explicit named recovery nodes are emitted as error-level diagnostics and prevent source formatting or semantic mutation. Tools may continue presenting the recoverable tree for editor feedback, but must not attach recovered fields or UUIDs to domain actions. Deterministic repairs should be offered as narrow source-edit code actions rather than a whole-document formatting pass.
Severity Levels
Linter rules are categorized into three levels that map to LSP diagnostic severity:
- Errors: Logical inconsistencies that block core functionality (e.g., an empty window, circular dependencies)
- Warnings: Semantic issues that don’t block functionality but may indicate problems (e.g., completed parent with uncompleted children, invalid dates)
- Info: Style violations and process improvements (e.g., metadata order, completed date missing)
Linting vs Formatting
- Formatter enforces presentation (spacing, indentation, layout) - automatic, opinionated, zero-config
- Linter detects semantic issues, temporal problems, and style preferences - optional, configurable, informative
- Parser validates syntax with relaxed acceptance
The formatter handles everything about how code looks. The linter handles everything about what code means and whether it’s correct, consistent, or following best practices.
A linter is optional and configurable - teams choose which rules to enforce based on their workflow. The formatter runs automatically (e.g., on save) and needs no configuration.
Design Principles
- Relaxed parsing, strict linting - Parser accepts most input, linter validates rigorously
- Non-destructive - Linters report issues, they don’t automatically fix semantic problems
- Configurable - Rules have severity levels (error, warning, info) and can be disabled
- Helpful - Messages guide users toward fixes with clear explanations
- Fast - Checks should be efficient enough for real-time editor integration
- Layered - Rules grouped by concern (correctness, style, best practices)
Rule Categories
1. Correctness (Errors)
These rules detect logical inconsistencies that block core functionality. These are NOT parse errors - the parser accepts this input, but the linter identifies semantic problems.
E001: Duration Without Do-Date (Retired)
**Fixable:** No
This rule is retired as of Decision 51.
Duration is no longer written; it is the length of the `@` block, so a
duration cannot exist without a do-date.
E002: Invalid Habit Recurrence (restored under Decision 57)
Fixable: No
A Habit root in .habits.actions requires R: with a valid RFC 5545 RRULE and an @ recurrence anchor. A missing rule/start, invalid rule, or recurrence in a template is a violation: on a Habit’s inline child, or on any line of a named template (templates/<name>.actions). A template is stamped below each occurrence and does not recur itself, so generating from a template with R: is refused (process.md). Validate FREQ, rule-part values and COUNT/UNTIL exclusion using RFC 5545. Preserve malformed source for diagnostics; do not guess a rule or a date. All open Habit states ([ ], [-], [=]) generate; only [x] completed and [_] cancelled stop generation. No state pauses a Habit. Both closed states require %, and open states must not carry a closed date, as with Actions (I001/I002).
Habit scope and template warnings
R: in ordinary .actions is a semantic warning (in a template it is E002): move the intended Habit to the charter’s .habits.actions rather than stripping recurrence silently. A habits root with both children and a template: <name> directive warns; children win. Missing persisted Habit or template-step ids block deterministic stamping and are reported for explicit identity minting. Unresolved transport-identity relationships must remain visible and must not silently merge native identities.
E003: Empty Context Tag
**Fixable:** No
Context tags cannot be empty, including whitespace-only tags or trailing commas.
```actions
[ ] Task +
[ ] Task +work,,home
[ ] Task +
[ ] Task +work,
```
E004: Orphaned Child Marker
**Fixable:** No
Child actions (`>`) must follow a parent action at the appropriate depth.
```actions
>[ ] No parent
[ ] Parent
>[ ] Child
```
E005: Skipped Hierarchy Level
**Fixable:** No
Cannot skip depth levels (e.g., depth 0 → depth 2).
```actions
[ ] Root
>>[ ] Skipped depth 1
[ ] Root
>[ ] Depth 1
>>[ ] Depth 2
```
E006: Invalid UUID Format
**Fixable:** No
UUIDs must follow standard format: `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` (UUIDv7 recommended).
```actions
[ ] Task #not-a-uuid
[ ] Task #123
[ ] Task #abc-def-abc-def
```
UUIDs are critical for the unique identification of actions across files and systems.
V7 adds the benefit of being time-sortable, which is useful for tracking creation order.
A half-typed but well-formed uuid prefix (`#01950000-0000-7000-8000`) is *not*
an E006 error — it is the live-buffer case handled by W013 (Incomplete UUID).
E006 is reserved for ids that no further typing repairs into a uuid at that
position.
E007: No State Brackets
**Fixable:** Yes
```actions
bad action
[ ] good action
```
State is a fundamental part of the syntax and actions without state are considered invalid
E008: Empty Window
**Fixable:** No
An Action's effective window (its own `:` intersected with every ancestor's)
opens at or after it closes, so the Action can never be done on time; or its
`@` block ends at or before it starts.
```actions
[ ] Submit forms :2026-12-15/2026-11-01
[ ] Enrollment :2026-11-01/2026-12-15
>[ ] Submit forms :2026-10-20
[ ] Call the plumber @2026-10-03T09:30/2026-10-03T09:00
```
**Rationale:** a window is a constraint from the world; an empty one is a
contradiction, not a plan (Decision 48). An empty block is the same mistake
in intent (Decision 51).
E009: Dependency on an Ancestor
**Fixable:** No
An Action has a predecessor (`<`) that resolves to one of its ancestors:
its parent, its parent's parent, and so on, up to a Habit root above its
template steps.
```actions
[ ] Plan the trip =trip
>[ ] Book flights < trip
[ ] Weekly review =weekly @2026-11-09T09:00/2026-11-09T10:00 R:FREQ=WEEKLY
>[ ] Clear the inbox < weekly
```
**Rationale:** a child is already related to its ancestors by the
hierarchy, so the dependency adds nothing. It is also a contradiction: a
parent closed while a descendant is open is itself reported
([process.md](./process.md#on-child-actions)), so a child waiting on its
parent waits on something that waits on it, the W007 cycle in another
form. A Habit's state is its whole series, so a step waiting on its Habit
would wait for the series to end. Stamping refuses such a template step.
**Fix suggestion:** drop the dependency, or point it at a sibling or
another Action outside the line's ancestry.
2. Warnings
These rules check for suspicious date/time relationships.
W001: Hierarchy Depth Exceeded
**Fixable:** No
Maximum nesting depth is 5 levels (depth 0-5).
```actions
[ ] Root >>>>>>[ ] Too deep (depth 6)
[ ] Root >>>>>[ ] OK (depth 5)
```
This may or may not be a breaking issue depending on parser implementation. but either way, the process also discourages deep nesting for clarity.
W002: Closed Parent with Open Children
**Fixable:** No
Reports the contradiction of a closed parent with an open child.
Here, "closed" means either completed (`[x]`) or cancelled (`[_]`).
This is a warning, not a prohibition on closing an individual action.
```actions
[x] Parent
>[ ] Open child
[_] Parent
>[ ] Open child
```
**Rationale:** Closing changes only the named action, so a closed parent can still have open child work. This warning surfaces that inconsistency; archive separately requires a wholly closed root tree.
W003: Open Parent with All Children Closed
**Fixable:** No
A parent action that remains open while all of its children are closed should likely be closed as well.
Here, "closed" means either completed (`[x]`) or cancelled (`[_]`).
```actions
[ ] Parent
>[x] Child 1
>[_] Child 2
```
**Rationale:** Serves as a nudge to the user to wrap up the parent action once all its sub-tasks are finished.
W004: Missing Creation Date (Retired)
This rule is retired. Creation provenance is persisted in the action sidecar and
may be bootstrapped from a UUIDv7 timestamp; it is not required to appear as a
^ field in every .actions line. An implementation must not warn merely
because the plaintext field is absent.
W005: Creation Date in Future
**Fixable:** No
The creation date (`^`) cannot be in the future relative to the current system time.
```actions
[ ] Task ^2099-01-01
```
W006: Completion Before Creation
**Fixable:** No
The completion date (`%`) cannot be before the creation date (`^`).
```actions
[x] Impossible Task ^2026-01-03 %2026-01-01
```
W007: Circular Dependency
**Fixable:** No
Actions cannot have circular dependencies (directly or transitively).
```actions
[ ] Task A =task-a < task-b
[ ] Task B =task-b < task-a
```
**Rationale:** Circular dependencies are logically impossible — neither action can ever be completed.
**Fix suggestion:** Review the dependency structure and break the cycle by removing or reworking one of the dependencies.
W008: Invalid Predecessor Reference
**Fixable:** No
A predecessor references an action that doesn't exist in the workspace.
```actions
[ ] Task < nonexistent-alias
```
**Rationale:** Actions should only depend on other actions that actually exist.
**Fix suggestion:** Check the UUID or alias spelling, or create the missing predecessor action. Names are not references ([Reference Syntax](reference_syntax.md#matching-rules)); give the predecessor an alias.
W009: Ambiguous Predecessor Reference
**Fixable:** No
Multiple actions in the workspace match the predecessor at its strongest tier, such as the same alias in two charters or a short UUID shared by two actions ([Reference Syntax](reference_syntax.md#matching-rules)). The reference does not resolve. Use a path or a full UUID to disambiguate.
```actions
[ ] Deploy < setup # charters inbox and release both have =setup
[ ] Deploy < release/setup
[ ] Deploy < 01951111-cfa6-718d-b303-d7107f4005b3
```
**Rationale:** A reference must name exactly one action; resolution never picks by file or collection order.
**Configuration:** `require_uuid_for_ambiguous_predecessors` (default: false) — if true, escalates to error severity.
W010: Duplicate Alias
**Fixable:** No
Multiple actions in the workspace define the same alias.
```actions
[ ] First task =deploy
[ ] Second task =deploy # Duplicate alias
```
**Rationale:** Aliases must be unique for unambiguous reference resolution.
**Fix suggestion:** Rename one of the aliases to be unique.
W011: Ambiguous Short UUID
**Fixable:** No
Multiple UUIDs in the workspace share the same 8-character prefix.
```actions
[ ] Task A #01951111-aaaa-aaaa-aaaa-aaaaaaaaaaaa
[ ] Task B #01951111-bbbb-bbbb-bbbb-bbbbbbbbbbbb
[ ] Task C < 01951111 # Ambiguous - matches both
```
**Rationale:** Short UUID references should resolve to exactly one action. While prefix collisions are rare, they can occur.
**Fix suggestion:** Use the full UUID or an alias for the reference.
W012: Sequential Marker on Childless Action
**Fixable:** No
The `~` marker is used on an action with no children.
```actions
[ ] Single task ~ # No children to sequence
```
**Rationale:** The sequential marker only affects child actions. Using it on a leaf action has no effect and may indicate a mistake.
W013: Incomplete UUID
**Fixable:** No (requires user input)
A `#id` that is a well-formed *prefix* of a full UUID but stops short — the
live-buffer case of a uuid still being typed. Distinguished from E006 (an
invalid id) by shape: the characters so far all sit in their template slots
(hex where the template is hex, `-` at positions 8/13/18/23) and at least one
`-` is present.
```actions
[ ] Task with a uuid still being typed #12345678-1234
[ ] Task with a truncated hyphenated uuid #01950000-0000-7000-8000
```
**Rationale:** The grammar accepts a malformed `#id` permissively rather than
erroring the whole line (Decision 6, relaxed parser / strict linter), so a
half-typed id reaches the linter as raw text. An id mid-edit is not a mistake
to error on — so this warns rather than errors. It still matters: an
unfinished id is replaced by a generated UUIDv7 on load, so the author's
intended id is lost if they never finish it. Contrast E006, which errors on a
genuinely invalid id (`#123`, `#abc-def`, `#not-a-uuid`) that no amount of
further typing turns into the uuid at that position.
W014: Decision Heading in an Action Description
**Fixable:** No (move the decision into DECISIONS.md and link to it)
A decision-labelled Markdown heading (`## Decision: ...`, `# Decision 42 ...`)
or a line beginning `Decision <number>:` inside an action description
duplicates the decision record. An action may cite a decision inline;
`Decision 42`, `DECIDED 2026-09-18`, and `RESOLVED ...` in ordinary prose
are not headings and are not flagged. Fenced Markdown examples are ignored.
The diagnostic points to the action.
**Rationale:** Decisions have one authoritative home in DECISIONS.md;
actions track work and link to that decision rather than copying its text.
W015: Planned Outside the Window
**Fixable:** No
The planned block, the `@` range, falls outside the Action's effective
window: it starts before the window opens, or ends after it closes. A date
covers its day, so `@2026-11-01` is inside a window opening `2026-11-01`;
and both ends are exclusive, so
`@2026-12-15T23:00/2026-12-16T00:00` is inside a window closing `2026-12-15`.
```actions
[ ] Submit forms @2026-10-20 :2026-11-01/2026-12-15
[ ] Submit forms @2026-12-15T23:30/2026-12-16T00:30 :2026-11-01/2026-12-15
```
**Rationale:** `@` is intent and bounds nothing, so planning outside the
window is allowed but probably a mistake. Work that really can happen
earlier, such as preparing, belongs in its own Action (Decision 48).
3. Style and Conventions (Info)
I001: Closed State Requires Completed Date
**Severity:** Info
**Fixable:** No (requires user input)
Actions in a closed state — completed (`[x]`) or cancelled (`[_]`) — must have a completed date (`%`).
```actions
[x] Task $ Description !1
[_] Cancelled task $ Description
[x] Task $ Description !1 %2025-01-20T15:00
[_] Cancelled task $ Description %2025-01-20T15:00
```
**Rationale:** Closure tracking requires knowing *when* the action left the open set, whether by completion or cancellation.
**Fix suggestion:** Add `%YYYY-MM-DDTHH:MM` or change state to an open state such as `[ ]`.
I002: Completed Date Requires Closed State
**Severity:** Info
**Fixable:** No
Actions with completed date (`%`) must have a closed state: `[x]` (completed) or `[_]` (cancelled).
```actions
[ ] Task %2025-01-20
[x] Task %2025-01-20
[_] Cancelled task %2025-01-20
```
**Rationale:** A completed date without a closed state is contradictory.
We may consider a distinct reopen date if requested, but for now `%` means the action was closed at that timestamp.
I003: Invalid Priority Level
**Severity:** Info
**Fixable:** No
Priority must be 1-9 (1 = highest, 9 = lowest), aligned directly with RFC 5545 `PRIORITY`.
```actions
[ ] Task !0
[ ] Task !6
[ ] Task !high
[ ] Task !1
```
**Rationale:** Priority levels are defined by the format specification.
While we dont necessarily stop you from putting higher values, for the sake of the process, we conform to the eisenhower matrix
I004: Duplicate ID
**Severity:** Info
**Fixable:** No
Action IDs must be unique within the file (and ideally across the project).
```actions
[ ] Task1 #00000000-0000-0000-0000-000000000000
[ ] Task2 #00000000-0000-0000-0000-000000000000
```
**Scope:** File-level check is mandatory. Cross-file checking is optional (requires project context).
These rules enforce team conventions and best practices. All are configurable.
I006: Metadata Order
**Severity:** Info
**Fixable:** Yes (if auto-reordering is enabled)
Metadata should follow canonical order: `$` → `!` → `*` → `+` → `@` → `D` → `%` → `#`.
```actions
[ ] Task !1 $ Desc # Priority before description
[ ] Task $ Desc !1 # Canonical order
```
**Configuration:** `enforce_metadata_order` (default: false)
**Rationale:** Consistent ordering improves scanability across files.
I007: High Priority Without Do-Date
**Severity:** Info
**Fixable:** No
Priority 1-2 actions without do-dates may need scheduling.
```actions
[ ] Critical task !1 # High priority but no schedule
[ ] Critical task !1 @2025-01-20
```
**Configuration:** `high_priority_threshold` (default: 2)
I008: Blocked Without Description
**Severity:** Info
**Fixable:** No
Blocked actions (`[=]`) should explain why in the description.
```actions
[=] Task !1
[=] Task $ Waiting for API access !1
```
I009: Child Higher Priority Than Parent
**Severity:** Info
**Fixable:** No
Child actions with higher priority than parents may indicate organizational issues.
```actions
[ ] Parent !3
>[ ] Child !1 # Higher priority than parent
[ ] Parent !1
>[ ] Child !2
```
**Configuration:** `check_child_priority` (default: false)
We keep the hierarchy limited for process requirements but many
I010: Excessive Duration
**Severity:** Info
**Fixable:** No
A very long `@` block may indicate a data entry error.
```actions
[ ] Task @2025-01-20T09:00/2025-01-27T09:00 # 1 week = 168 hours
[ ] Task @2025-01-20T09:00/2025-01-20T11:00 # 2 hours
```
**Configuration:** `max_duration_minutes` (default: 480 = 8 hours)
I011: Past Do-Date on Not-Started Action
**Severity:** Warning
**Fixable:** No
Actions with state `[ ]` (not started) probably shouldn't have do-dates in the past.
```actions
[ ] Task @2020-01-01 # Several years ago
[x] Task @2020-01-01 %2020-01-02 # Completed in the past is fine
[ ] Task @2026-01-20 # Future is fine
```
**Rationale:** Likely indicates stale actions that should be updated or archived.
**Configuration:** `past_do_date_threshold_days` (default: 7) - how many days past before warning.
I012: Invalid Alias Format
**Severity:** Info
**Fixable:** No
Alias names should contain only alphanumeric characters, underscores, and hyphens.
```actions
[ ] Task =my alias # Spaces not allowed
[ ] Task =my@alias # Special chars not allowed
[ ] Task =my-alias # Valid
[ ] Task =my_alias # Valid
```
**Rationale:** Aliases are used as identifiers and should be simple, machine-friendly strings.
I013: Redundant Tag (Covered by Hierarchy)
**Severity:** Info
**Fixable:** Yes
An action is tagged with both a child tag and its ancestor tag from the configured hierarchy.
```actions
# Given config: terminal includes neovim
[ ] Task +neovim,terminal # "terminal" is redundant
[ ] Task +neovim # Correct - "terminal" is implied
```
**Rationale:** The child tag already implies the parent. Listing both adds noise without value.
**Configuration:** Requires `tag_hierarchies` to be configured.
I014: Story Path Depth Excessive
**Severity:** Info
**Fixable:** No
Story paths with more than 4 levels may indicate over-organization.
```actions
[ ] Task *work/dept/team/project/subproject/epic # 6 levels deep
[ ] Task *work/clearhead/cli # 3 levels - reasonable
```
**Configuration:** `max_story_path_depth` (default: 4)
**Rationale:** Deep hierarchies become hard to navigate and may indicate scope creep.
I015: Empty Alias
**Severity:** Info
**Fixable:** No
An alias marker `=` is present but no alias name follows.
```actions
[ ] Task =
[ ] Task =deploy # Valid
```
**Rationale:** An alias marker without a name serves no purpose.
Reference Syntax for ClearHead Formats
Throughout this work we make liberal usage of id fields, whether that be within the DSL or within the markdown files that are used for the higher order structures.
However, in order to support multiple forms of identifiers, we support multiple reference formats.
UUID
The first, and strongest reference is a full UUID.
now, within our system we generally do:
- UUIDv7 as a default
- UUIDv5 for actions that can deterministically be namespaced to a particular plan.
For programmatic structures, it is generally recommended to use the full UUID format for clarity and to have the least option for collisions, especially by two independent applications.
short UUID
However, for user-facing references, we support a short UUID format that is at least the first 4 characters of the UUID, as this is generally enough to avoid collisions within a single workspace, and is easy to read for humans when necessary.
When multiple UUIDs share a short prefix, the reference must include as many characters as are needed to disambiguate. Clients MUST accept prefixes longer than eight characters; an ambiguous prefix does not resolve by collection or file order.
Alias
The second (and preferred) form of reference is by alias.
Aliases are short, human-readable identifiers. They are the primary way to reference charters and actions in day-to-day use.
In formats where the filesystem is used, a charter alias is often reflected in the file or directory name, again namespaced within the domain where it is kept. Action aliases are authored explicitly in the action DSL.
Plans do not currently have aliases. RFC 5545 provides UID for stable identity and SUMMARY for a mutable display name, but no standard alias property. Plans therefore use their UUID for ClearHead references; SUMMARY is not a reference. A distinct Plan alias would require an explicit extension property and is not part of the current format.
in this way, we can have clean aliases that are still easy to reference based on the work of the structures inside
On Paths
Sub-entities can use / to denote a sub path.
this way we can easily refer to subcharters, subplans, and even both in tandem if necessary while remaining readable.
for example if we have the following plan:
inbox.actions [ ] something > [ ] sub
we can refer to sub as something/sub and if this were to be referenced with the charter we could write: inbox/something/sub to make reference of aliases easier
this works because each element creates a new namespace so that two charters can have identical actions without being semantically different as their relationships distinguish them
Alternate separators
while the / separator is the default for paths, alternate separators can be used if necessary to avoid conflicts with aliases that may contain /. For example, . or - could be used as separators in such cases.
Prefix Disambiguation
In ambiguous cases or for tooling, you can prefix a reference to force the target type:
c:<ref>for charterp:<ref>for plana:<ref>for act
Prefixes are optional but recommended when a segment could resolve to multiple types.
Resolution Outcomes
Resolution failures have stable semantic categories so callers do not need to classify human-readable diagnostics:
- empty — no reference text was supplied;
- invalid syntax — a prefix has no value or the path has no segments;
- not found — the reference is valid but no entity matches in scope;
- ambiguous — multiple entities match at the strongest available tier;
- type mismatch — a typed path resolves, but to a different entity type.
Diagnostics may add contextual names and remediation. Programmatic consumers should branch on the category rather than parsing that text.
Matching Rules
- Charters and actions match aliases or UUIDs only (full UUID or short UUID prefix).
- Plans match UUIDs only (full UUID or short UUID prefix).
- Matching precedence is full UUID, then short UUID, then alias, across the complete candidate set.
- Multiple matches at the strongest tier within a workspace are ambiguous and MUST NOT resolve by collection or file order.
- References are case-insensitive for aliases.
- Titles, names, and Plan
SUMMARYvalues are not used for reference resolution. - Action aliases are scoped by their containing path; UUIDs remain the strongest unambiguous form.
Charter Documentation
Charters are the primary way that we organize plans within the platform. they are prose markdown documents that leverage combination of frontmatter and content to give users a way to organize plans and actions around a particular domain of concern.
Frontmatter
for the purposes of organization and reading, frontmatter allows charters to contain some important metadata, while still remaining largely a prose document for human consumption
in this structure, we are primarily concerned with what is needed to give this structure meaning within the platform and link it with other parsed works meaning we have:
- id: a unique UUIDv7 for the charter that can be linked (optional in the file: a document without one still loads with an ephemeral identity and
doctorreports it; see Concept Identity in workspace.md)
this is the only required field for now if a charter DOES exist within the platform that will be used
The workspace root charter is no exception: its frontmatter lives in charters/README.md. See The Root Charter.
Optional Frontmatter
- title: a human readable title for the charter, this is optional because it can be derived
- alias: an aptional-short name for the charter that can be used for reference
- aliases are scoped within the namespace of their parent charter
- parent: the reference of the parent charter, this allows for nesting charters within charters, and is optional because not all charters need to be nested
- parents must be denoted with either the reference syntax or through the UUID of the parent
- however this model is SECONDARY to the model outlined in things like the naming conventions
- Note: in a file-based workspace you almost never need this field — directory placement is the primary and preferred way to express charter hierarchy (see workspace.md). This field exists for non-filesystem contexts or genuinely disconnected structures where placement cannot express the relationship.
- parents must be denoted with either the reference syntax or through the UUID of the parent
- objectives: a list of references to objectives within the platform that this works in servie of
- state: the Charter’s locally asserted lifecycle state:
New— defined but not admitted for engagementActive— locally eligible for engagementBlocked— unable to advanceClosed— finished and terminalCancelled— abandoned and terminal
- defaults: any settings that shoud be applied to all descendants of the charter. primarily good for controlling structure and making consistent actions more alike. primarily done by setting key value pairs within the defaults dictionary.
When state is omitted, semantic projections must expose it as New; omission
must not be interpreted as Active. Effective engagement also requires every
ancestor Charter to be Active. This inherited eligibility is derived and never
rewrites the local state.
A Charter known only through its actions, with no document, is likewise New,
and so is every newly created Charter. New is the planning state: creating a
Charter does not mean its work is ready, and it usually needs more planning
before it is. Activation is therefore always an explicit, requested transition.
No operation that creates or edits a Charter’s document may change its state as
a side effect, and a document created for an existing Charter declares New
unless that transition was requested. Because a New Charter’s open actions are
invisible to engagement, implementations should report a New Charter that owns
open actions.
Other states are permissible, but these are the minimum states Charter implementations must support. State transitions do not implicitly cascade to descendant Charters or Actions. The normative admission, readiness, transition, and contradiction rules are defined in Process Overview.
Closed and Cancelled are both terminal states: either makes a Charter
eligible for archival (see Archive).
Content
For the purpose of the content, charters only need a single header and content below it
# Example Charter Title
with some description text
in this way, the first header serves as the title and the content serves as the description
even the description is optional, as the title is the only required content for a charter to be valid, but the description can be used to give more context about the charter and its purpose
Another option is the use of the title property:
---
title: charter example
---
here is a small charter description
This mirrors common linter conventions for markdown
Extra Sections
All subsections are included in the description while sibling sections are meant to be seen as extra content that can represent whatever is needed but will be saved separately when archived
charter logs
A charter’s log is its notes: a running record of the semantic activity within the charter, kept in its JSON sidecar under notes.<charter id> and appended by clearhead jot. It is not part of the charter document, so a reader of the charter’s text, a worker brief included, gets the core and not the history.
format
A log entry is a note {at, by, text}. at is an ISO 8601 date-time with its UTC offset (2026-09-17T23:28-07:00), since entries from different machines share one log and must order correctly; tools that write entries always include it. by and text are as for any note. Entries are appended, so their order in the array is their order in time. Editors may render at in a friendlier form, but the stored value stays ISO 8601.
The legacy ## Log section
Charters written before notes may have a ## Log section beneath the core section, a list whose items each begin with an ISO 8601 date or date-time, followed by — and the entry text. Readers still accept it, as a log read before the charter’s notes, until a charter is migrated. Tools never append to it. An entry without a leading date is read as undated text, and implementations must not add a date to an existing entry: the time of that edit is not the time the entry was written. Migration moves each entry to a note, keeping its text and its date; a date without a time gives at the date at midnight UTC (2026-09-17T00:00Z), so every reader of a migrated entry agrees on the instant, and by is omitted where unknown. A migrated charter has no ## Log section.
example (legacy)
# test
test charter
## Log
- 2026-09-17 — log line 1
- 2026-09-17T23:28-07:00 — log line 2
Objective File specification
Objectives, like charters, are a core domain object that represent the desired outcomes that plans and actions serve. They are the “why” behind the “what” of plans and actions.
Like charters, they use frontmatter to determine data, and content to give a prose explanation of the object itself
Frontmatter
The frontmatter for objectives is relatively simple, as the only required field is the id, which is a UUIDv7 that can be used to link this objective with other objects within the platform. An objective file without an id is reported and not loaded; nothing mints one for it on read.
Optional Frontmatter
title: a human readable title for the objective, this is optional because it can be- however this will generally be the header instead
alias: an optional short name for the objective that can be used for reference- otherwise the objective is named by its file:
<name>.mdis<name>, and a directory-form<name>/README.mdis<name> - the root objective,
objectives/README.md, has no file name to fall back on: its name is the workspace’sworkspace_name, which a frontmatteraliasoverrides
- otherwise the objective is named by its file:
parent: the reference of the parent objective, this allows for nesting objectives within objectives, and is optional because not all objectives need to be nested
these serve the reference syntax for objectives: a charter’s objectives entries name an objective by its alias or its id, as charter parent references do. Titles are for display and are never matched, since they change.
The Root Objective
Every workspace has one root objective, objectives/README.md, as it has one root charter, charters/README.md: what the whole workspace is for. A plan without an objective is not yet a plan, so the root charter names the root objective in its objectives. clearhead init creates both, writing the objective’s alias from workspace_name so that renaming the workspace later cannot rename the objective out from under the charters that name it, and the root charter’s objectives naming it (see Initialization). In a workspace that predates this, doctor reports any charter that names no objective; loading never refuses one.
Metrics
For objectives that have a measurable outcome, we can also include a metrics field in the frontmatter that contains a list of metrics to be measured including:
name: the name of the metric, this is required for the metric to be validdescription: a description of the metric, this is optional but can be used to givetarget: the target value for the metric, this is optional but can be used to give a clear goal for the metric
these small metrics allow for measurable objectives that can be later linked to data systems that track the actual data for runtime calculations of steps
A metric says what success looks like, not when to check it. Reviewing a metric is work: an action, recurring or with a due date, in a charter that serves the objective.
Content
For the purposes of parsing, the first H1 header is assumed to be the title of the objective, and the content below it is assumed to be the description of the objective.
# Example Objective Title
with some description text
this is a simple objective with the title “Example Objective Title” and the description “with some description text”
Workspace
One aspect that is orthogonal, but important to consider is how workspaces are structured, discovered, and identified when it comes to collections of action files.
In particular, we want it to be ergonomic to manage multiple “containers” whether you call them stories or projects, by leveraging the filesystem.
While the file specification defines how individual action files are structured, this specification defines how those files should be organized and named within a workspace.
They are separate, because different implementors may choose to work with the format, but choose to avoid these conventions which is fine, this way implementors can absorb specifications a-la-carte and take on the complexity they want to consider.
Scoping
For our work we generally have 3 scopes to consider:
- Machine-Wide Scope: Config
- User Scope: Data + Config
- Project Scope: Data + Config
As is standard, each level is less prioritized than the next, so project scope overrides user scope which overrides machine-wide scope.
The user-scope data is for data that belongs to the user of that actual machine but is not generally attached to a given project and its location is configured via the XDG_DATA_HOME environment variable, with a default of ~/.local/share/ for unix systems and %APPDATA% for windows systems.
This defined by the presence of a .clearhead directory. This may be empty as to only express a desire for this to be designated a project-local scope
- while the default will be that this is in the root of the git directory, the algorithm itself will simply look for the nearest
.clearheaddirectory and designate that as the project root, this way we can have multiple projects within a single git repository if desired, or even have a project that is not attached to a git repository at all
Workspace Structure
All action files/folders should be organized into a directory that conforms with the standards of the given operating system.
Please see Configuration for details on locating the global workspace location and how to configure it.
In general the data should reside in XDG_DATA_HOME/clearhead/. The workspace root is a container for parallel top-level concepts — not a dump of mixed files:
<workspace>/
├── archive/ ← closed history, as plaintext; mirrors charters/ layout
├── charters/ ← acts (.actions), markdown (.md), json sidecars
├── plans/ ← vdir calendars; one subdirectory per charter
├── objectives/ ← objectives live here
└── templates/ ← act templates live here
This scoping makes discovery trivial: implementors scan charters/ for charter content and plans/ for schedule data, without needing exclusion lists. The archive/ region is a sibling of charters/, so it falls outside the default read for free, while staying plaintext and parseable when something needs to look into it.
The root charter’s charters/next.actions (see The Root Charter) is the default location for uncategorized acts: capture lands at the top of the tree, and filing into a child charter is a later step. No other file is special. A charters/inbox.actions, where one exists, is an ordinary child charter named inbox.
Recovered source is quarantined from semantics
A relaxed parser may return a document containing recovery diagnostics so doctor, the linter, and editor tooling can explain malformed input. Such a document is not eligible for semantic workspace lowering: generic parser recovery can attach a later field or UUID to the wrong action. The affected action file is omitted from the domain model until it parses with clean integrity, while a structured finding remains visible. Formatting and mutation likewise require the clean source capability; they must never reserialize recovered actions. Sidecar orphan cleanup is also deferred while any action source is quarantined, because absence from the semantic model is not proof that its provenance is stale.
Example
So if we go over the structure of the work we can see this as an example with a global and project workspace at the examples directory.
this shows both the project and user scope for examples of mixed layouts that would be representative of real world usage
Objectives
Objectives are all located in an objectives directory within the workspace where all objectives of the file format: <objective-alias>.md - a markdown file containing the description of the objective, its purpose, and any other relevant information as per the objective spec
objectives/README.md is the root objective, mirroring the root charter’s charters/README.md: what the workspace as a whole is for. The root charter names it in its objectives (see The Root Objective).
in a project-local scope, this should reside within <project-root>/.clearhead/objectives/ while in a user-wide scope, this should reside within objectives/ folder within the user workspace
Sub Objectives
objective files within the objectives directory are assumed to be a group of objectives,
with:
<objective-alias>/README.md- a markdown file containing the description of the objective group, its purpose, and any other relevant information as per the objective spec<objective-alias>/<subobjective-alias>.md- a markdown file containing the description of the subobjective, its purpose, and any other relevant information as per the objective spec
this allows implementors to organize subobjectives within the directories without worrying about namespace colisions as the alias is scoped within the parent objective alias
Charters
charters belong in the dedicated charters directory within the workspace, where each charter is represented as a markdown file or a directory containing a README.md file.
While the action specification allows for charters to be defined within the files themselves, it can often feel natural to break these files into separate files/folders for organization.
To this end, we support the following conventions, with the assumption implementors will leverage these structures to provide better user experiences.
- we can also designate
<charter>.mdfiles for charters that are primarily prose and not action-focused, but still want to be linked to actions within the platform- please see the charter spec for more details on how to structure these files
- This allows for sub-projects through the combination of directories and files.
$workspace/charters/<charter-name>/README.md- A file containing a description of the charter, its purpose, and any other relevant information as per the charter spec
all closed charters are moved into the archive/ region along with their children to keep a complete record — as their original plaintext files, not a serialized form
All charters and subcharters live within the charters/ directory. Users are free to symlink README files from the project root into .clearhead/charters/ if desired, but the canonical location is always within charters/.
The root charter declares its alias in charters/README.md frontmatter, like every other charter. It is never inferred from the directory name at load time; see The Root Charter.
Hierarchy
While actions express hierarchy through the file format, charters express hierarchy through placement.
Specifically, while we do support parent as front matter, the primary way that lineage is created is by placing subcharters and their plans in the directory of its parent.
In this way, we can structure charters and subcharters
The Root Charter
Every workspace, project or user, has exactly one root charter, and every other charter descends from it: flat charters in charters/ are its direct children, and nested placement expresses deeper lineage. Scope changes how a workspace is discovered and which name init seeds, never the shape of the root.
The root is the charters/ directory itself, anchored by reserved file roles:
charters/README.md— the root’s prose and identity anchor; its frontmatter carriesidandaliasexactly as any charter’s doescharters/next.actions— the root’s action anchor, the same stem every directory-form charter uses for its own actions (charters/<charter>/next.actions)charters/.next.json— the root’s sidecar, mirroring the frontmatteridplans/next/— the root’s plan collection (vdir directory)
next names a file role, not a charter: there is no charter entity named next, so a named charter can never collide with the root. Unlike a directory-form charter, the root cannot take its name from its directory, which is always charters/; its name is its frontmatter alias.
Root identity is charter identity and follows the concept identity rules: minted once, persisted in charters/README.md, read from there. It is distinct from workspace identity: workspace_name seeds the root’s alias at init, after which the two are independent facts. Neither is ever recomputed from the working directory or the environment.
A root without charters/README.md or without its id still loads as the single root. Like a workspace without a workspace_id, it gets an ephemeral identity that is never persisted and never derived from a path, and its display name falls back to workspace_name. A root with no README, or a README that omits state, is New like any charter without a declared state; because engagement requires every ancestor to be Active, nothing in the workspace is admitted for engagement until the root is activated. clearhead init fills in missing root files and writes the root as New, since a workspace starts in planning; doctor reports the gap; loading never writes identity or state. When the README and sidecar disagree, the README wins: doctor --fix mirrors its id into the sidecar only when nothing references the replaced id, and otherwise reports a violation to reconcile by hand.
Sidecar for data
we can also add the .<charter-name>.json sidecar file that allows users to place data that is relevant to the charter but not something that should be kept in the files themselves.
This will cover all the pieces we will be going over and has various properties to link different objects together at a data level without cluttering the core files themselves
please review the charter sidecar schema for more details on how to use this file and its properties.
Notes
Any entity can carry notes: a charter, an Action, a Habit. Notes are the one uniform log of the workspace, kept in the sidecar of the charter whose file holds the entity, under a top-level notes map keyed by the entity’s UUID: notes.<uuid> is an array of notes, oldest first. A note is {at, by, text}:
at: an ISO 8601 date-time with its UTC offset, the instant the note was written.by: who wrote it, in the convention the docs’ front matter uses:human:Darrion,agent:<role>. Optional only for notes migrated from a legacy log.text: plain text.
The tools treat notes as an append-only log. clearhead jot is the single verb that writes one and takes any entity’s id; a correction is a new note, and no tool edits or deletes one. The JSON can still be edited by hand, so readers accept what they find (unordered notes, a missing by) rather than refusing it; they order by at, ties by position.
Appending is not a mutation of the entity. It works in any state, closed and archived included, never touches the .actions line or the charter document, and so cannot disturb a description. Appends are serialized, by a lock or by compare-and-retry: two writers appending at once never lose a note.
Notes follow the entity. Readers take the union of every sidecar keyed by UUID, so a note reaches its entity wherever the line now lives. doctor --fix therefore relocates rather than prunes: a notes entry whose entity lives in another charter moves to that charter’s sidecar, and an entry whose entity exists nowhere is reported and kept, never deleted. (Other orphaned sidecar entries remain prunable.) Archiving moves the sidecar whole, notes included.
Descriptions that already carry dated additions are not migrated automatically.
Note: we use the hidden file convention here to indicate that this is a sidecar file meant to be read and written by tools as a companion to the charter, but should not be directly interacted with by users.
Plans
A workspace’s <data_root>/plans/ directory stays a charter-scoped iCalendar vdir (Decision 31). A one-off Plan projects an Action’s @ block; a recurring Plan projects a Habit held in a habits file. Unscheduled Actions have no Plan resource.
Every constructed charter owns one calculated collection path even when its directory does not exist. This relative path is derived from the charter’s canonical workspace anchor and is not written into charter Markdown or sidecars. The vdir’s location is part of the workspace layout, not configuration, and it belongs to exactly one workspace; transport tooling points at it where it is. Calendar resources attach to charters by exact collection ownership, never by mutable alias or title matching.
Each .ics file contains one VCALENDAR with a VEVENT master and same-UID recurrence overrides. VTODO is not part of this calendar integration. ClearHead-created filenames use UID, but readers identify resources by UID because transport may rename files.
This one-component-per-file vdir layout is directly compatible with tools such as vdirsyncer and does not assume a particular CalDAV server or any transport at all.
Any charter with plans requires directory form. The plans/ directory itself signals that a workspace has schedule data.
All paths are relative to <data_root>/plans/. An example:
-
next/<uid>.ics -
work/<uid>.ics -
work-feature/<uid>.ics -
subproject/<uid>.icswhich maps to charters:
-
the root charter (
nextis its reserved plan collection) -
workcharter -
work/featuresub-charter (hierarchy encoded with-) -
subprojectcharter
Multi-component .ics files are an import format, not a storage format. Implementations should provide an import path that splits them into individual resources within the target charter’s plans/ directory.
An immediate collection directory with no charter owner is invalid workspace state, not an alternate way to create a charter. Its resources must not be silently adopted; the ownership problem remains visible for explicit resolution.
Be sure to review the reference syntax for guidance on working with sub charters and sub plans.
For recurring Plan, standalone Action, identity, and synchronization semantics, see the ICS Schedule Spec.
Actions
Per the Ontology specification, actions are the actual executable work items in the system, whether they are generated from plans or created directly.
Actions are stored in the .actions files within the workspace and represent the lowest atomic unit of work within the system.
Ordinary .actions files hold executable Actions, including occurrences and one-offs, not recurrence. All these files use the same actions syntax: R: parses regardless of file role, but has recurrence meaning only on Habit roots in a habits file. R: on an ordinary Action or template child is a semantic lint, not a parse error; see Linting. Calendar event object semantics belong to the .ics projections and semantic sidecars, not these action lines. A charter’s <charter>.habits.actions holds Habit roots, their R: rules and optional template children. Directory-form charters and the root use next.habits.actions, beside next.actions, sharing .next.json. Habits and their template children must never be lowered as live executable Actions or inferred as extra charters.
Moving a line between an ordinary actions file and a habits file, adding or removing R:, retains its UUID. The moved entity changes kind; it does not remain in both files or become its own generated occurrence. See kind-change outcomes.
All paths are relative to charters/:
charters/<charter>.actions— unarchived Actions for that charter, including closed lines and every arrived Habit occurrencecharters/<charter>.habits.actions— Habit definitions and their template childrencharters/next.actions— root charter acts (project or user workspace root)charters/<charter>.completed.actions— archived whole root trees for that charter; closed lines are not moved here merely by closing (see Archival)charters/<charter>/next.actions— root acts for a folder-form charter
When a charter is archived, its known files (charters/<charter>.actions, .completed.actions, .habits.actions, the charter .md, and its .json sidecar) and every other charter-local supporting file in a directory-form charter (notes, inventories, and future formats) are moved verbatim into the archive/ region, at the path they held under charters/. Nothing is serialized: the archived form is the same plaintext, just relocated out of the default read set.
Readers classify .habits.actions and .completed.actions before the general .actions suffix, removing the entire known suffix to find the charter stem. Discovery, parsing, lowering, mutation, archive, lint/doctor, RDF publication and editor navigation must all use that classification. The same files must neither be discovered twice nor leak template children or archived occurrences into the live Action index. Test root, flat and directory charters, archive moves and unrelated supporting files. Archive-aware duplicate suppression still reads terminal occurrence lineage.
Charter stem derivation follows the same rules as plan name inference: next.actions in a directory-form charter uses that directory’s name; charters/next.actions is the root’s reserved anchor and takes its name from charters/README.md (see The Root Charter); all other .actions files use the file stem.
Concept Identity
Every concept in a workspace — the workspace itself, its charters, its plans, and its actions — carries a durable identity that survives renames, moves, and edits. Identity belongs to the concept, never to its file path or title, so a reference resolves to the same thing after the target is renamed, reordered, or moved (including into an archive).
One lifecycle governs all four:
mint or derive once → persist to the concept’s anchor → read from persistence →
doctorreconciles drift
They differ only in where the identity is persisted:
| Concept | Anchor | Specified in |
|---|---|---|
| Workspace | workspace_id in <data_root>/workspace.json | Workspace Identity |
| Charter | frontmatter id, mirrored in the sidecar | Charters |
| Plan | transport VEVENT UID, linked to native identity in sidecars | [ICS Schedule Spec] |
| Habit | inline #uuid in the habits file, retained on kind moves | [Action File Format], [ICS Schedule Spec] |
| Action | inline id; its sidecar records the UID of any realized Plan | [Action File Format], [ICS Schedule Spec] |
Three rules keep this honest:
-
Tool-managed, not typed. Humans never write a UUID;
init, the CLI, and the LSP mint and maintain them. “Invisible” means unobtrusive, not absent — a mutable action line carries its id quietly rather than re-deriving one on every read. -
Derivation is a bootstrap, never a live recompute. An identity may be derived once to fill a gap and then persisted as truth. Recomputing an id from mutable content — from a title, from a path — is forbidden: change the content and you silently change the identity, orphaning every reference to it. A broken reference must fail loudly, into a dangling id that
doctorcan report, rather than rebinding silently to a different concept. -
A missing anchor is a reportable gap, not a write. A concept whose anchor has not been written yet — a charter document with no
id, like the root README above, or a workspace with noworkspace_id— still loads: the reader supplies an ephemeral identity that is never persisted and never derived from content or path, anddoctorreports the gap. Loading never writes identity, and no ordinary edit stamps one as a side effect. A durable id is minted only by a deliberate identity-minting pass, or when a whole new document is created. Anything that would persist an identity — an archive file name, a sidecar record — requires a declared one, and refuses otherwise.
Actions carry their charter
An action may record its charter’s id alongside its own, denormalizing the action→charter link so it survives independently of which file the action currently sits in. The embedded charter id is authoritative when present; the file’s location is the fallback when it is absent. doctor reconciles the two on conflict.
Named Graph Isolation
Each workspace maps 1-1 to an RDF named graph. This enables querying a single workspace in isolation or spanning multiple configured workspaces without data coalescing into a single undifferentiated graph. See Decision 28 for the rationale.
Workspace Identity
A workspace’s identity is its workspace_id, stored in its own <data_root>/workspace.json manifest — deliberately separate from config.json. The data root is the directory holding charters/ and plans/: <project>/.clearhead/ for a project workspace, and the resolved data_dir (default $XDG_DATA_HOME/clearhead/) for the user workspace. The manifest’s location follows that one rule in both scopes:
{
"workspace_id": "019e43e4-...",
"workspace_name": "platform",
"created_at": "2026-05-31"
}
The manifest and config.json are split because they are different in kind. config.json holds behavior — human-authored preferences that layer through the precedence chain (global → project → project.local → env → args). Identity is a tool-managed fact about one workspace that must not layer: a workspace_id in a global config, or a CLEARHEAD_WORKSPACE_ID env override, is meaningless. Keeping identity in a non-layered manifest keeps the config precedence rules honest. The manifest is near-static — it changes on init and rename, essentially never otherwise — and carries workspace-level facts only; per-charter, per-action, and per-plan metadata live in their co-located sidecars, never here. See the manifest schema.
The named graph URI is derived from it as urn:clearhead:workspace:<workspace_id>.
workspace_id is assigned once by clearhead init and remains stable for the life of the workspace — it is the durable handle for the workspace’s named graph, so any consumer that names the graph URI resolves it to the same workspace across sessions. It is never regenerated in normal operation.
That stability is a convenience, not a correctness requirement. A workspace without a workspace_id is fully queryable: the read side mints an ephemeral graph identity per load — distinct per workspace, never persisted, and never derived from the root path. Such a workspace answers queries correctly; its graph URI simply is not stable across sessions. init is how a workspace earns a durable URI — offered, never forced.
workspace_name is the display name used in multi-workspace output and cross-workspace reference syntax (name:charter/action). init persists it once: --name when given, otherwise the project directory name for a project workspace or the current username for the user workspace. Readers use the persisted value and never recompute it from the directory or environment; it can be edited manually afterwards.
created_at records when the workspace was initialized. Informational only.
Query Scope
Query scope is determined by the additional_workspaces configuration:
- Single workspace (default): Only the current workspace’s named graph is loaded and queried.
- Multi-workspace: When
additional_workspaceslists additional workspace paths, all of them are loaded into the same store alongside the current workspace — each in its own named graph. Queries span all loaded named graphs.
The scope is declared in config, not per-command. A user who configures additional workspaces intends cross-workspace visibility by default. This means the platform repository, which lists all submodule workspaces as additional_workspaces, queries across all of them without any additional flags.
Initialization
clearhead init bootstraps a project workspace at <cwd>/.clearhead/; clearhead init --user bootstraps the user workspace at the resolved data_dir. Both accept --name and perform the same steps against their data root:
- Generates a UUIDv7 and writes
workspace_id,workspace_name,created_atto<data_root>/workspace.json(skipped ifworkspace_idalready present). If an older project workspace still carries these fields in.clearhead/config.json,initanddoctormigrate them into the manifest and drop them fromconfig.json. - Creates the
charters/directory structure and bootstraps the root charter (each file skipped if already present):charters/README.mdwith a mintedidand analiasseeded fromworkspace_name,charters/next.actions, and thecharters/.next.jsonsidecar mirroring thatid. These files are structural: they let flat named charters resolve as children of the root and keep their plan-vdir slugs routable. - Bootstraps the root objective (skipped if already present):
objectives/README.mdwith a mintedidand analiasseeded fromworkspace_name. When step 2 createscharters/README.md, itsobjectivesnames that alias; an existing root charter is never edited, anddoctorreports it if it names no objective.
init is idempotent — rerunning it on an already-initialized workspace is safe and never overwrites existing data or identity. It may restore a missing root-charter scaffold. Pass --force to regenerate identity fields. This assigns a new graph URI, so any consumer that referenced the old one no longer resolves to this workspace; the workspace’s plaintext data is untouched.
Workflows
Now, its one thing to speak on the concrete file formats for each record type but the other piece to cover is the workflow that actually handled these various structures and dictates what happens when and where. for this, we are going to go a little more over the workflows that allow this format to be updated automatically or manually based on what people prefer
Templates
Templates are a list of actions in the form of <name>.actions files that are stored in a templates/ directory at the root of the workspace. these are meant to be used as templates for generating actions either through schedules or on demand.
it is assumed that the filename will be the reference for the template, so if we have a weekly-review.actions file in the templates/ directory, then the reference for that template will be weekly-review and this is used in a Habit’s description as template: weekly-review, projected to the recurring VEVENT DESCRIPTION (first line of calendar notes)
this will also allow for on demand generation of actions either as a side-effect to charter creation or through a command like apply template which will allow users to generate actions from templates on demand without needing to wait for the schedule to trigger them
Archival
One concept that is very important to the workspace format is the process of “archiving” things. weve covered the names above but its working from a reference point lets go from the beginning
- At the lowest level, we have the actions that are implementations of their optional parent plans.
- Closing an action changes only that line’s state and stamps its completion date in place; it does not close descendants, detach a parent link, or move the line. Closed lines in
<charter>.actionsare ordinary active-file records. Only archive and unarchive move action lines between<charter>.actionsand<charter>.completed.actions, always as a whole root tree (a root and everything below it). Archive accepts a closed root only when its whole tree is closed, and transfers that tree to the completed file. Unarchive accepts a root in the completed file and returns its whole tree to the active file without changing states. Both operations refuse a child target and name its root instead. Parent links within an archived tree are kept. Reopening is a separate in-place state change: it sets only the named action tonot_startedand clears its completion date. Reopen is allowed only in the active file; an archived action must be unarchived first. - Habits have their own state: completing or cancelling the Habit ends generation without closing its open occurrences. Their definitions move with the charter’s known files; calendar projections have no independent work lifecycle.
- Finally, like plans, the charters themselves at
charters/<charter>.mdcan be archived after they are closed. Archival is a move, not a translation: the archived form is data, not a projection, so no Turtle or JSON-LD is written. Any RDF view of archived data is regenerated from the loaded domain model by Core’s publication adapter, exactly like live data. - archiving a parent charter archives its whole subtree as one unit; the open-actions precondition is recursive too — it refuses if any descendant still holds open actions
- the subtree’s known files (
.actions,.completed.actions,.habits.actions, the charter.md, and its.jsonsidecar) plus all supporting files owned by directory-form charters are moved into thearchive/region together, preserving their path undercharters/so the subtree’s internal structure survives. The sidecar moves with the files rather than folding itscreated_at/external_schedule_idinto the lines. An implementation must make the move safe to interrupt and retry: a file may transiently exist in bothcharters/andarchive/, but it is never removed fromcharters/without already existing inarchive/— redundant, never an orphaned or lost record - any charter subdirectory left empty by the move is collapsed
Because archive/ is a sibling of charters/, the moved files leave the default read set automatically, but reference resolution can still look into them: an archived < target resolves to one of three states — satisfied (target Completed), abandoned (target Cancelled), or dangling (resolves nowhere). Keeping archives as readable plaintext is the whole reason that three-way signal is possible.
The .ics files in plans/<charter-name>/ are not touched by archival. Per decision 31, the plans vdir is a shared projection boundary and archival must not infer that its resources should be deleted. Archived Action records retain history while the vdir remains independently manageable through calendar tooling. A collection left without a live charter owner is invalid workspace state and must remain visible for explicit resolution; it is never silently adopted as an implicit charter.
REMEMBER, per the process spec it is assumed that all child plans are completed/cancelled which is why the open files above are expected to be empty or atleast emptyable before being moved into archive/
this is how we maintain a format that is able to evolve gracefully
See Also
- [Action File Format] — DSL syntax
- Charters — Charter structure and frontmatter
- Configuration — XDG paths and config settings
- [ICS Schedule Spec] — VEVENT projection, synchronization, and schedule semantics
- Ontology — Domain model and RDF contract
- Process — Workflow including recurring action behavior
- [Reference Syntax] — Sub-charter and sub-plan references
ClearHead Configuration Specification
Overview
This specification defines how ClearHead implementations handle configuration, including directory structure, file format, configuration layering, and extension mechanisms.
Key principles:
- XDG Base Directory compliance for portability
- JSON format for universal compatibility
- Layered configuration for flexibility
- Shared core settings with implementation-specific extensions
Directory Structure
On Scoping
The platform supports user-level data as well as project-specific data.
please see Workspace for details on how to name project-specific files and directories. but for the configuration, we want to allow users to avoid this entire process with the default_to_user_scope setting that will bypass this searching algorithm entirely and ONLY show the domain model for the user scope.
Additional workspaces
If users want to have multiple repos pulled into the same domain model, they can update the additional_workspaces setting with a list of entries pointing to directories that follow the standard .clearhead workspace layout. Each workspace retains its own named graph in the RDF store so charters and actions can be attributed to their source when displaying multi-workspace results.
Entries support three formats, all through the same interface:
| Format | Example | Use case |
|---|---|---|
| Relative path | "../sibling-project" | Sub-projects or sibling repos on the same machine |
| Absolute path | "~/work/other-project" | Workspaces elsewhere on the filesystem; ~ and environment variables are expanded |
| URL (planned) | "https://example.com/team-workspace" | Remote workspaces; not yet implemented |
Relative paths are resolved from the directory containing config.json. Shell expansion (~, $HOME, $VAR) applies to all path-based entries.
XDG Base Directory Compliance
All implementations MUST follow the XDG Base Directory specification:
| Directory Type | Location | Default |
|---|---|---|
| Config | $XDG_CONFIG_HOME/clearhead | ~/.config/clearhead |
| Data | $XDG_DATA_HOME/clearhead | ~/.local/share/clearhead |
| State | $XDG_STATE_HOME/clearhead | ~/.local/state/clearhead |
| Cache (optional) | $XDG_CACHE_HOME/clearhead | ~/.cache/clearhead |
Default File Structure
~/.config/clearhead/
└── config.json # Primary configuration file
~/.local/share/clearhead/ # User data root (data_dir), bootstrapped by `clearhead init --user`
├── workspace.json # Workspace manifest: identity facts
└── charters/
├── README.md # Root charter: id + alias frontmatter
├── next.actions # Root charter action anchor; the default capture file
└── .next.json # Root charter sidecar
On Project-Specific Config
Within the example of a specific project, these subdirectories all reside within the .clearhead directory:
project_root/
└── .clearhead/ # Project data root, bootstrapped by `clearhead init`
├── workspace.json # Workspace manifest: identity facts, committed (see below)
├── config.json # Project configuration, committed and shared (optional)
├── config.local.json # Personal override, git-ignored (optional)
├── .gitignore # Ignores config.local.json (written by `clearhead init`)
└── charters/
├── README.md # Root charter: id + alias frontmatter
├── next.actions # Root charter action anchor
├── .next.json # Root charter sidecar
└── ... # Other charters
Both scopes share one shape; see The Root Charter.
config.json is committed so the whole team shares workspace behavior (additional_workspaces, tag_hierarchies, plan_component, …). config.local.json sits beside it as a git-ignored personal override: a single developer can set their own values (e.g. their own plan_component) without touching the shared file. The local file wins over the committed one. clearhead init writes a scoped .clearhead/.gitignore so the personal override stays out of version control.
Workspace identity — workspace_id, workspace_name, created_at — does not live in config.json. It lives in a separate <data_root>/workspace.json manifest. The two are split because they behave differently: config.json is human-authored behavior that layers through the precedence chain below, while the manifest is a tool-managed fact about one workspace that must not layer (a workspace_id in a global config, or a CLEARHEAD_WORKSPACE_ID env override, is meaningless). The manifest is committed and near-static — it changes on init and rename, essentially never otherwise — and holds workspace-level facts only; per-charter metadata stays in its co-located sidecar. See Workspace Identity and the manifest schema.
Configuration File Format
Format Choice
Configuration MUST be stored in a Format that supports conversion to-and-from JSON format at $XDG_CONFIG_HOME/clearhead/config.json.
Rationale for JSON:
- Universal support across all languages and platforms
- Native support in most editors
- Simple, well-understood format
Configuration Structure
The configuration file uses a flat structure with implementation-specific namespacing:
- Core settings - Shared across all implementations (no prefix)
- Implementation settings - Prefixed with implementation name (e.g.,
cli_*,nvim_*)
Core configuration example:
{
"data_dir": "~/.local/share/clearhead",
"config_dir": "~/.config/clearhead",
"default_file": "next.actions"
}
With implementation-specific settings:
{
"data_dir": "~/.local/share/clearhead",
"default_file": "next.actions",
"cli_format": "table",
"cli_indent_style": "spaces",
"cli_indent_width": 4,
"nvim_auto_normalize": true,
"nvim_format_on_save": true,
"nvim_lsp_enable": true
}
Core Settings
All implementations MUST recognize these core settings:
| Setting | Type | Default | Description |
|---|---|---|---|
data_dir | string | ~/.local/share/clearhead | Global directory for user data and action files |
config_dir | string | ~/.config/clearhead | Global directory for configuration files |
state_dir | string | ~/.local/state/clearhead | Directory for machine-specific runtime state and event logs |
default_file | string | next.actions | Default capture file (relative to the workspace’s charters/ directory) |
tag_hierarchies | object | {} | Tag parent-child relationships for implicit inheritance |
default_to_user_scope | boolean | false | If true, only shows user-scoped actions (ignores project scope) |
additional_workspaces | array | [] | Additional workspaces to merge into the domain model. Entries may be relative paths, absolute paths (with ~ / env-var expansion), or URLs (planned). See Additional workspaces. |
plan_component | retired | — | Plans use VEVENT only (Decision 55). A legacy vtodo value warns; linked resources have a one-release conversion path in the ICS specification. |
expansion_total_instances | integer | 2 | Bound on read-only future planning projections only. Never a cap on arrived Habit occurrences or a reason to drop missed slots. Write-path catch-up may be bounded per transaction but must resume until every arrived slot is represented. |
Requirements:
- Core settings MUST support shell expansion (
~,$HOME, environment variables) - Relative paths in
default_fileMUST be resolved from the workspace’scharters/directory - Absolute paths MUST be used as-is
Workspace Resolution
Which workspace an invocation operates on is resolved by most-local context first, independent of configuration precedence below:
- Project workspace — walk up from the working directory to the first ancestor containing a
.clearhead/directory (Workspace). - Configured user workspace — the
data_dirsetting, when set. - Default user workspace —
$XDG_DATA_HOME/clearhead.
data_dir relocates the fallback user workspace only; it MUST NOT override a detected project workspace. Bypassing project detection is an explicit choice via default_to_user_scope, never a side effect of other settings.
Configuration Precedence
Implementations MUST follow this precedence order (highest to lowest):
- Command-line arguments - Highest priority (CLI tools only)
- Environment variables -
CLEARHEAD_*prefix - Project-local configuration -
<project-root>/.clearhead/config.local.json(git-ignored, personal) - Project configuration -
<project-root>/.clearhead/config.json(committed, shared) - Global configuration -
$XDG_CONFIG_HOME/clearhead/config.json - Built-in defaults - Hardcoded in the application
The two project layers let a committed config.json carry the shared workspace settings while each developer keeps personal overrides in a git-ignored config.local.json beside it — the local file wins. Both are optional and only apply when the invocation resolves to a project workspace.
Layering Example
Built-in default: cli_format = "actions"
Global config: cli_format = "json"
Environment: CLEARHEAD_CLI_FORMAT=xml
CLI flag: --format compact
Result: compact (CLI flag wins)
Environment Variables
Naming Convention
Environment variables MUST use the CLEARHEAD_ prefix followed by setting names in uppercase with underscores.
Core settings:
CLEARHEAD_DATA_DIR=/custom/path
CLEARHEAD_CONFIG_DIR=/custom/config
CLEARHEAD_DEFAULT_FILE=work.actions
Implementation-specific settings use the same prefix pattern with implementation namespace:
# CLI settings (maps to cli_* in JSON)
CLEARHEAD_CLI_FORMAT=json
CLEARHEAD_CLI_INDENT_STYLE=tabs
CLEARHEAD_CLI_INDENT_WIDTH=2
# Neovim settings (maps to nvim_* in JSON)
CLEARHEAD_NVIM_AUTO_NORMALIZE=false
CLEARHEAD_NVIM_FORMAT_ON_SAVE=true
CLEARHEAD_NVIM_LSP_ENABLE=true
Value Parsing
Implementations MUST parse environment variable values as follows:
"true"/"false"→ boolean- Numeric strings → numbers
- JSON arrays (e.g.,
'["a", "b"]') → arrays - All other values → strings
- Empty values are treated as not set (fall through to next precedence level)
Implementation-Specific Settings
Extension Mechanism
Implementations MAY add their own settings to the configuration file using a namespaced prefix (typically the tool name in lowercase followed by an underscore).
Example for multiple implementations:
{
"data_dir": "~/.local/share/clearhead",
"default_file": "next.actions",
"cli_format": "table",
"cli_indent_style": "spaces",
"cli_indent_width": 4,
"nvim_auto_normalize": true,
"nvim_format_on_save": true,
"nvim_lsp_enable": true,
"sync_enabled": true,
"sync_relay_url": "wss://sync.example.com",
"sync_interval_seconds": 30,
"web_port": 8080,
"web_auto_sync": true,
"web_theme": "dark"
}
Requirements:
- Implementations MUST prefix their settings with a unique namespace (e.g.,
cli_,nvim_,sync_,web_) - Implementations MUST ignore settings from other namespaces
- Implementations SHOULD NOT depend on settings from other namespaces
- Namespace prefixes MUST be unique identifiers (no conflicts)
- Core settings (no prefix) MUST be respected by all implementations
Tag Hierarchies (tag_hierarchies)
Tag hierarchies define parent-child relationships between context tags. When an action is tagged with a child tag, it implicitly inherits all ancestor tags.
Structure:
{
"tag_hierarchies": {
"parent_tag": ["child_tag_1", "child_tag_2"],
"another_parent": ["child_tag_3"]
}
}
Each key is a parent tag, and its value is an array of child tags that should inherit from it.
Example:
{
"tag_hierarchies": {
"computer": ["terminal", "browser", "ide"],
"terminal": ["neovim", "tmux", "shell"],
"driving": ["grocery_store", "gas_station", "pharmacy"],
"work": {"project_a": ["design", "development", "testing"]},
"low_energy": ["email", "reading", "filing"]
}
}
Semantics:
- Transitive inheritance: If
terminalis a child ofcomputer, andneovimis a child ofterminal, then+neovimimplicitly includes both+terminaland+computer. - Query expansion: Searching for
+computerwill match actions tagged with+neovim,+terminal,+browser, etc. - Linting: Actions tagged with both a child and its ancestor receive an info-level warning (I013) about redundancy.
- Case-insensitive: Tag matching is case-insensitive.
Use cases:
- GTD contexts:
@errands→@grocery,@pharmacy,@bank - Energy levels:
@low_energy→@email,@reading - Tools:
@computer→@terminal→@neovim - Locations:
@office→@desk,@meeting_room
Schema Extension
Implementations SHOULD provide their own JSON schema that extends the core schema:
Core schema (config.schema.json in this spec repository):
{
"$schema": "http://json-schema.org/draft-07/schema#",
"type": "object",
"properties": {
"data_dir": { "type": "string" },
"config_dir": { "type": "string" },
"default_file": { "type": "string" }
},
"additionalProperties": true
}
CLI extension (in clearhead-cli repository):
{
"$schema": "http://json-schema.org/draft-07/schema#",
"allOf": [
{ "$ref": "https://raw.githubusercontent.com/.../config.schema.json" }
],
"properties": {
"cli_format": { "type": "string", "enum": ["actions", "json", "xml", "table"] },
"cli_indent_style": { "type": "string", "enum": ["spaces", "tabs"] },
"cli_indent_width": { "type": "integer", "minimum": 1, "maximum": 8 }
}
}
This allows:
- Validation tools to check configuration correctness
- Editors to provide autocomplete and documentation
- Forward compatibility as new implementations are added
Implementation Guidelines
Path Resolution
Implementations MUST handle paths as follows:
- Absolute paths (starting with
/or~/): Use as-is after shell expansion - Relative paths: Resolve from
data_dir - Shell expansion: Support
~,$HOME, and other environment variables - Platform normalization: Handle path separators appropriately
Example:
{
"data_dir": "~/Documents/clearhead",
"default_file": "next.actions"
}
Resolves to: ~/Documents/clearhead/charters/next.actions
Error Handling
Implementations SHOULD:
- Missing config: Gracefully degrade to defaults (don’t error)
- Invalid JSON: Provide clear error with line number
- Unknown fields: Warn but don’t fail (forward compatibility)
- Missing directories: Create automatically with appropriate permissions
- Missing additional workspace: Skip an
additional_workspacesentry that does not exist, in every verb, with a warning naming the entry;doctorreports it. Never create it: the entry is stale config, not a directory to initialize, and one stale entry must not break work in the others - Invalid values: Use defaults and warn
Example error message:
Warning: Invalid JSON in ~/.config/clearhead/config.json:12
Unexpected token '}' at line 12, column 3
Falling back to default configuration.
Performance
Implementations SHOULD:
- Cache resolved configuration in memory
- Re-read only when file modification time changes
- Avoid file I/O on every operation
- Validate configuration once at startup
Directory Initialization
On first run, implementations SHOULD:
- Create config directory if missing
- Create data directory if missing
- Optionally create example
config.jsonwith commented defaults - Bootstrap the root charter’s anchors if missing (see Initialization)
Examples
Minimal Configuration
The simplest valid configuration overrides just one setting:
{
"default_file": "work.actions"
}
All other settings use defaults.
Full Configuration
{
"data_dir": "~/Dropbox/clearhead",
"config_dir": "~/.config/clearhead",
"state_dir": "~/.local/state/clearhead",
"default_file": "next.actions",
}
Environment Variable Overrides
Environment variables can override configuration file settings:
# Use different data directory for this session
export CLEARHEAD_DATA_DIR="~/work-projects/clearhead"
# Override CLI format preference
export CLEARHEAD_CLI_FORMAT="json"
# Disable format-on-save in Neovim
export CLEARHEAD_NVIM_FORMAT_ON_SAVE="false"
# Run commands - they'll use overridden values
clearhead_cli read
nvim charters/next.actions
Conformance
An implementation is conformant with this specification if it:
- Follows XDG Base Directory specification for config, data, and state locations
- Reads configuration from
config.jsonin JSON format - Respects all core settings (
data_dir,config_dir,state_dir,default_file) - Implements configuration precedence correctly (defaults → global config → project config → project.local config → env → args)
- Uses
CLEARHEAD_*prefix for environment variables - Handles missing/invalid configuration gracefully with defaults
- Supports shell expansion in path values
- Uses namespaced prefixes for implementation-specific settings (e.g.,
cli_,nvim_,sync_) - care should be taken to avoid conflicts remember this is a global namespace
See Also
- Action File Format - Core file format
- Workspace - File and directory naming
Changelog
See CHANGELOG.md for version history and updates to this specification.
Ontology & Linked Data
Draft (platform Decisions 45 to 53, 56 and 57, charter emit-the-ontology). Implementations publish the application graph defined here; v4 is retired.
A conforming implementation publishes a workspace as the application graph: RDF in ClearHead’s application vocabulary, app:, defined here. It is what queries read and what an export writes. What each app: term means is defined by its mapping to CCO v2.2 and IAO terms, the ClearHead ontology (see its domain reference); an app: term asserts nothing its mapping does not, and every term has one. The CCO graph below is that meaning, written out for the conformance fixture. The SHACL shapes in schemas/ test both graphs (Decision 42).
Entity roles
- Objectives are higher-level outcomes.
- Actions are concrete executable units of work.
- Habits are recurring prescriptions that generate Actions, not executable Actions themselves.
- Plans are editable calendar projections of Action blocks and Habits, not a second authority for the work.
File placement is defined in Workspace.
Canonical RDF Dataset
This is the normative, engine-neutral contract for the RDF that ClearHead publishes. A conforming implementation produces this dataset from a validated workspace whether or not any SPARQL engine is present.
The single projection is authoritative for every ClearHead RDF statement. JSON-LD is a serialization of this same dataset, never a second export path, and it MUST preserve the same facts and graph identity.
Publication Boundary
- The plaintext workspace is the only canonical write model. RDF is a deterministic, replaceable snapshot of it.
- The read path is one-way:
plaintext workspace -> validated domain model -> RDF dataset. - Missing triples are not workspace deletions; external graph mutations do not sync back into plaintext.
- There is no generic RDF import, no remote endpoint proxy, and no round-trip that recovers workspace source (files, line layout, formatting) from RDF.
- Query results address mutation verbs through the same
urn:uuid:...identities the CLI accepts.
Named Graph Identity
Every workspace occupies exactly one named graph, urn:clearhead:workspace:<uuid>, where <uuid> is the stable workspace_id from <data_root>/workspace.json (see Workspace — Named Graph Isolation). TriG and N-Quads preserve it; Turtle and compact JSON-LD carry one graph and lose it.
Application Graph
Namespace https://clearhead.dev/vocab/app/v1#, prefix app:. Also used: rdfs: http://www.w3.org/2000/01/rdf-schema#, dcterms: http://purl.org/dc/terms/, skos: http://www.w3.org/2004/02/skos/core#, xsd: http://www.w3.org/2001/XMLSchema#.
Rules
- Standard terms where they fit. A name is
rdfs:label, a descriptiondcterms:description, a creation timedcterms:created, a context hierarchyskos:broader.app:names only what ClearHead adds. - Written and derived terms. A written term carries a value as the file states it. A derived term is computed from the files and the viewer’s context (the zone in Time), so queries need not recompute it; it is never written back, and it is mapped to CCO like any other term. Each derived term below says how it is computed.
- Where an entity is kept.
app:fileis the path of the file holding it, relative to the data root (the directory holdingcharters/,plans/andobjectives/), with/separators and no leading./.app:lineis the 1-based line where an action starts. The graph names no root; a client resolves paths against the data root it already knows. If another backend has no files, these are absent. - IRIs. An entity from a file is
urn:uuid:<id>. A context isurn:uuid:<UUIDv5(context namespace, slug)>(see Context terms). A metric isurn:uuid:<UUIDv5(objective id, "metric/<slug>")>, its slug made as a context’s is. A Habit uses its persisted line UUID, just as an Action does (see Habit terms). No blank nodes. - Containment points up. A part
app:partOfits whole: a child action its parent action, a top-level action its charter, a Habit its charter, a charter its parent charter, an objective its parent objective. Each has at most one. - Every action, Habit, charter and objective has exactly one
app:statewhose value is one of the IRIs in State values. Absent fields emit nothing.
Action terms
An action is app:Action. Fields are those of actions.schema.json.
| Field | DSL | Terms |
|---|---|---|
id | # | The IRI. |
name | text | rdfs:label |
description | $ … $ | dcterms:description |
state | [ ] … | app:state (below) |
priority | ! | app:priority, an integer |
contexts | + | app:context, per tag, its context node |
scheduledDateTime | @ | app:plannedStart, written: when the action is planned; and app:plannedEnd, written, the block’s end when @ is an interval. Intent: bounds nothing (Decisions 48 and 51) |
dueDateTime | : | app:due, the deadline as written, and app:availableFrom, the window’s lower bound as written when : is an interval; see Time |
completedDateTime | % | app:closed, written: when the action was completed or cancelled |
createdDateTime | ^ | dcterms:created, written |
predecessors | < | app:after, per reference, the action it names; see Waits |
sequentialChildren | ~ | app:sequential true |
parentId, charter | >, the file | app:partOf (rule 5) |
alias | = | app:alias |
sidecar occurrence.habit_id | none | app:occurrenceOf, the native Habit whose occurrence this is; transport UID is not the Habit id |
sidecar occurrence.occurrence_key | none | app:slot, the canonical slot key as xsd:string: D: date, F: floating or U: UTC instant (ICS schedule specification) |
sidecar notes.<id>[] | none | app:note, per note, a blank node on the entity with rdf:value (text), dcterms:created (at, xsd:dateTime) and dcterms:creator (by, when present). Charters, Actions and Habits alike |
Derived: app:notBefore, app:lateFrom, app:plannedFrom, app:durationMinutes (Time) and app:waitsOn (Waits). Location: app:file, app:line.
State values
| Entity | app:state values |
|---|---|
| Habit | app:NotStarted [ ], app:InProgress [-], app:Blocked [=], app:Completed [x], app:Cancelled [_] |
| Action | app:NotStarted [ ], app:InProgress [-], app:Blocked [=], app:Completed [x], app:Cancelled [_] |
| Charter | app:New, app:Active, app:Blocked, app:Closed, app:Cancelled, from its state (app:New when unset) |
| Objective | Not yet defined (objectives gives objectives a state without naming its values); none is emitted. |
Time
app:plannedStart, app:plannedEnd, app:availableFrom, app:due, app:closed and dcterms:created are as written: a date alone is an xsd:date; a date and time is an xsd:dateTime of the form YYYY-MM-DDThh:mm:ss, with an offset or Z only if the file wrote one.
The window is : alone; @ is intent and bounds nothing (Decision 48). A date covers its day and a time is an instant (Decisions 47 and 51). The derived instants say when an action’s effective window opens and closes, each an xsd:dateTime with an offset:
app:notBefore: the first instant the action may be worked. The latest of its ownapp:availableFromand every ancestor action’s, taking a date’s first instant.app:lateFrom: the first instant the action is late. The earliest of its ownapp:dueand every ancestor action’s, taking where it ends: a date’s following midnight, a time itself.
A child with no bound of its own therefore inherits its parent’s, and one with its own narrows it (action file format). A time written without an offset, and every date, is resolved in the viewer’s zone, the zone in which the graph is projected, using the time-zone database. Queries compare these instants, never the written values: an xsd:date, a floating xsd:dateTime and one with an offset do not compare reliably in SPARQL.
The planned block is @, never inherited, and read as the window is.
app:plannedFrom: the first instant ofapp:plannedStart, anxsd:dateTimewith an offset: a date’s first instant, a time itself. Queries compare it, never the written start.app:durationMinutes: the block’s length in whole minutes, rounded down, from the first instant ofapp:plannedStartto the end ofapp:plannedEnd(a date’s following midnight, a time itself). Emitted only for an interval of at least a minute; a single@value has no duration.
Waits
app:after is each predecessor as written. app:waitsOn is derived: everything that must be closed before the action can start. It is the action’s own app:after targets, the sibling before it when its parent is app:sequential, and its parent action’s app:waitsOn. An action is free to start when every app:waitsOn target is completed or cancelled.
Charter terms
A charter (a charter document) is app:Charter.
| Field | Terms |
|---|---|
id | The IRI. |
title (H1 or title) | rdfs:label |
| body text | dcterms:description |
alias | app:alias |
parent | app:partOf the parent charter |
objectives | app:serves, per objective |
state | app:state |
| its file | app:file: the charter document, or its actions file if it has none |
Objective terms
An objective (an objective file) is app:Objective.
| Field | Terms |
|---|---|
id, title, body, alias, parent | As for charters; app:partOf the parent objective. |
metrics | app:metric, per metric, an app:Metric with rdfs:label its name, dcterms:description and app:target (text) when given. |
| its file | app:file |
Context terms
A plus-tag names a context: where, with what or by whom an action can be done (Decision 43). The set is open. Each tag is one app:Context, urn:uuid:<UUIDv5(context namespace, slug)>, with rdfs:label the slug (leading + stripped, trimmed, lowercased, spaces to -). The context namespace is the constant 0d8937ce-eb24-52d2-9532-39ea299f888b. It was minted as the UUIDv5 of https://clearhead.us/context under the RFC 9562 URL namespace, while names lived at that domain, and does not move with it: changing it would rename every context node. Hierarchies from workspace configuration are skos:broader, child to parent; a context named only as a parent is emitted too.
Habit terms
A Habit is anything done regularly: a root with recurrence in <charter>.habits.actions (Decision 57). It is app:Habit, not an executable app:Action. JSON uses the action fields plus recurrenceRule; inline children are template data, not live Action nodes.
| Native source | Terms |
|---|---|
#uuid | The IRI, urn:uuid:<uuid>. |
| name | rdfs:label |
| description | dcterms:description |
R: | app:rule, RRULE text; the graph does not take it apart |
@ | app:plannedStart, app:plannedEnd, as for an Action |
| state marker | app:state, per State values |
% | app:closed, when the Habit was completed or cancelled |
| named template directive | app:template, name as text; omitted when inline children win |
| charter | app:partOf (rule 5) |
| source location | app:file: the .habits.actions path; app:line: 1-based root line |
Derived: app:plannedFrom and app:durationMinutes, as for an action’s block (Time).
A Habit’s own state governs generation: all open states (app:NotStarted, app:InProgress, app:Blocked) generate arrived occurrences. app:Completed and app:Cancelled generate none, including catch-up, and each has its closed date. Rule exhaustion is not an implicit state write. The Habit state does not close its occurrences. There is no pause state: blocked still generates. To stop for a while, close and recreate the Habit; see Process.
Each occurrence is an ordinary action, app:partOf its charter, with app:occurrenceOf its Habit and app:slot the slot it fills (Action terms). app:occurrenceOf is not containment: the Habit does not hold its occurrences (Decision 56), and “a Habit’s occurrences” is the pattern ?occurrence app:occurrenceOf ?habit.
The old event-derived Habit namespace is retired. Native occurrence and stable template-step UUID derivation follow canonical slots, independent of transport UIDs or viewer zones.
Example
The line
[-] Call the plumber !2 +phone @2026-10-03T09:00/2026-10-03T09:15 :2026-10-03/2026-10-04 =plumber #01a0faa2-0000-7000-8000-000000000001
at line 1 of charters/next.actions, a top-level action of the root charter, projects in a UTC viewer’s zone as:
<urn:uuid:01a0faa2-0000-7000-8000-000000000001> a app:Action ;
rdfs:label "Call the plumber" ;
app:state app:InProgress ;
app:priority 2 ;
app:context <urn:uuid:aa0d0a8e-8a8b-5ef1-b25b-f894935d2d82> ; # phone
app:plannedStart "2026-10-03T09:00:00"^^xsd:dateTime ;
app:plannedEnd "2026-10-03T09:15:00"^^xsd:dateTime ;
app:availableFrom "2026-10-03"^^xsd:date ;
app:due "2026-10-04"^^xsd:date ;
app:notBefore "2026-10-03T00:00:00Z"^^xsd:dateTime ;
app:lateFrom "2026-10-05T00:00:00Z"^^xsd:dateTime ;
app:plannedFrom "2026-10-03T09:00:00Z"^^xsd:dateTime ;
app:durationMinutes 15 ;
app:alias "plumber" ;
app:partOf <urn:uuid:01a0faa2-0000-7000-8000-0000000000c0> ; # the root charter
app:file "charters/next.actions" ; app:line 1 .
Meaning: the CCO Graph
The mapping is
ontology/mapping/(Decisions 45 and 50): one SPARQL CONSTRUCT per structure, run over the application graph. This section describes what it produces; the queries are authoritative. The gate checks that mapping the fixture’sexpected-app.ttlyields itsexpected.ttl, and that every application term is read by a query or listed, with why, inontology/unmapped.ttl.
Conventions
These rules decide every row of the mapping below.
- Meaning the competency questions reason over uses the ontology’s patterns. State, priority, conditions (waits, contexts, energy, times), parts, objectives and records are CCO/IAO structures, as the domain reference gives them.
- Facts about the record itself are Dublin Core annotations. A long description and when an entry was written are metadata about an information entity:
dcterms:descriptionanddcterms:created, used as annotation properties, the way CCO annotates its own terms. Annotations carry no logical meaning, so the reasoner ignores them; they add no nodes and mint nothing. - The graph carries no storage facts. No file paths, line numbers, workspace roots or calendar identifiers (
UID,RECURRENCE-ID): they describe where a copy is kept, not the work, and would not exist in another backend. Queries return identities; where an entity is stored is answered by the implementation that stores it, from those identities. The workspace’s identity stays, as the named graph. - Literal values sit on a bearer. As CCO requires, a measurement or description carries its value through an Information Bearing Entity (
cco:ont00000253) thatis carrier ofit (obo:BFO_0000101), withhas text value(cco:ont00001765),has integer value(cco:ont00001773) orhas datetime value(cco:ont00001767). - Containment is published downward. A whole
has continuant part(obo:BFO_0000178) each part; the inverse is derivable and not emitted. - Entities keep their IRIs; helper nodes are blank (Decision 49). Actions, charters, objectives, metrics and contexts are IRIs; a condition, description, measurement, bearer, intent or act exists only as part of its owner and nothing outside the graph refers to it, so it is a blank node. Exports that must diff byte for byte are canonicalized with RDF Dataset Canonicalization (RDFC-1.0); fixtures compare by graph isomorphism.
- One condition per Performance Specification. Each wait, context, energy level or time is its own Performance Specification (
cco:ont00000127) whose parts are the action and one Descriptive ICE (cco:ont00000853) thatdescribes(cco:ont00001982) the condition. - Conditions are effective. An action carries every wait and window bound that applies to it, its own and those it inherits, read from
app:waitsOn,app:notBeforeandapp:lateFromrather than from the terms as written: one fact, one condition. An inherited condition is true of the child.
Prefixes: cco: https://www.commoncoreontologies.org/, obo: http://purl.obolibrary.org/obo/, dcterms: http://purl.org/dc/terms/, skos: http://www.w3.org/2004/02/skos/core#, rdfs: as usual.
Actions
An action (one line of a .actions file) is an IAO action specification, obo:IAO_0000007. Fields are those of actions.schema.json.
| Field | DSL | Representation |
|---|---|---|
id | # | The IRI, urn:uuid:<id>. No separate id triple. |
name | text | rdfs:label. |
description | $ … $ | dcterms:description (convention 2). |
state | [ ] … | See Action state. |
priority | ! | A Priority Measurement ICE (cco:ont00000369) that is an ordinal measurement of (cco:ont00001811) the action; integer on its bearer, 1 first. |
contexts | + | Per tag, a condition describing the context. |
scheduledDateTime | @ | Intent (Decision 48): a Prescriptive ICE (cco:ont00000965) that is part of the action, the planned start on its bearer; a block’s length is the duration below, so app:plannedEnd is not read. Not a condition, and no act exists until the work starts (ontology Decision 4). |
dueDateTime | : | The effective window (convention 8): per bound, a condition whose description’s bearer carries the text not before or late from and the instant, from app:notBefore and app:lateFrom. The time sits on the bearer, not on a BFO temporal instant designated through a CCO identifier, which would add two nodes per time. |
durationMinutes | derived from @ | A Measurement ICE (cco:ont00001163) is about (cco:ont00001808) the action; its bearer has the integer and uses measurement unit (cco:ont00001863) Minute (cco:ont00001667). |
predecessors | < | Per effective wait (app:waitsOn, convention 8), a condition describing the awaited action. |
sequentialChildren | ~ | Expanded through app:waitsOn: each child after the first waits on the child before it. The marker itself is not emitted. |
parentId, children | > | The parent has continuant part the child. A top-level action is a part of its charter. |
charter | * | No triple: membership is the containment above. |
alias | = | A Designative Name (cco:ont00000003) that designates (cco:ont00001916) the action; text on its bearer. |
createdDateTime | ^ | dcterms:created (convention 2). |
completedDateTime | % | The time on the bearer of the record that closed the action: the act’s completed status, or the cancelled measurement (below). |
sidecar occurrence.habit_id | none | Read through app:occurrenceOf: the Habit has continuant part the occurrence. |
externalOccurrenceKey | none | Not emitted (convention 3). |
Action state
State is never one field in the graph (ontology Decisions 4 and 5): what is shown is derived from records.
| State | DSL | Representation |
|---|---|---|
| Not started | [ ] | Nothing: no act, no status. |
| In progress | [-] | A Planned Act (cco:ont00000228) prescribed by (cco:ont00001920) the action, and an Event Status Nominal ICE (cco:ont00000203) that is a nominal measurement of (cco:ont00001868) the act, text in progress. |
| Completed | [x] | As in progress, text completed; the completion time, if any, as datetime on the same bearer. |
| Blocked | [=] | A condition describing something outside the data the action waits on: a Descriptive ICE with text waiting and no describes target. |
| Cancelled | [_] | A Nominal Measurement ICE (cco:ont00000293) that is a nominal measurement of the action itself, text cancelled; the cancellation time, if any, on the same bearer. |
Charters
A charter (a charter document) is a Plan, cco:ont00000974.
| Field | Representation |
|---|---|
id | The IRI. |
title (H1 or title) | rdfs:label. |
| body text | dcterms:description. |
alias | A Designative Name, as for actions. |
parent | The parent charter has continuant part this one. |
objectives | The charter has continuant part each objective. A charter with none is reported, never refused (Objectives). |
state | A Nominal Measurement ICE that is a nominal measurement of the plan, text new, active, blocked, closed or cancelled. |
| its actions | The charter has continuant part each top-level action. |
Objectives
An objective (an objective file) is an Objective, cco:ont00000476.
| Field | Representation |
|---|---|
id | The IRI. |
title, body, alias | As for charters. |
parent | The parent objective has continuant part this one. |
state | A Nominal Measurement ICE of the objective, confirmed by an agent (ontology Decision 5). |
metrics | Per metric, a Descriptive ICE is about the objective, its done-condition, keeping the metric’s IRI, with text <name>: <target> (or <name> with no target) on its bearer and its description as dcterms:description. |
Contexts
A plus-tag names a context: where, with what or by whom an action can be done (Decision 43). The set is open. Each tag is one node, urn:uuid:<UUIDv5(context namespace, slug)>, with rdfs:label the slug (leading + stripped, trimmed, lowercased, spaces to -). It is not typed: a tag may name a site, a tool, a person or a state of the doer, and the projection cannot know which. Hierarchies from workspace configuration are skos:broader, child to parent. This makes each context a skos:Concept by inference, which is harmless while SKOS is not merged with BFO for reasoning.
Habits
A Habit (a root in .habits.actions, projected as a recurring VEVENT, Decision 57) is an action specification that prescribes many acts (ontology Decision 6), a part of its charter. Its recurrence is a time condition like any other (convention 7), one that repeats: the condition’s description carries the RFC 5545 RRULE (app:rule) as text on its bearer. This specification owns the rule’s semantics; the graph does not take it apart. No BFO-family ontology structures a recurrence rule (searched CCO v2.2, IAO and the OBO library, 2026-10-01); the structured alternatives, schema.org Schedule and the W3C RDF Calendar ical:rrule, sit outside it. Cost: a query cannot tell a recurring condition from a one-off one except by its text. Revisit if a question ever needs to reason inside a rule.
Its first slot’s start (app:plannedStart) is an intent and its length a duration, as for an action. Its template (app:template) is not read: it says how ClearHead realizes an occurrence, not what the Habit prescribes.
Each occurrence is its own action specification, with its own scheduled or due condition, and a part of both its charter and its Habit: the Habit has continuant part each occurrence (app:occurrenceOf). Its slot (app:slot) is not read (convention 3). When an occurrence is done, its act is the calendar event: a Planned Act in its temporal region, as for any action.
Helper nodes
Every node that is not an action, Habit, charter, objective, metric or context is a blank node (convention 6). A query reaches it from its owner through the pattern its row gives, never by name.
A context node keeps an IRI of its own: the UUIDv5 of its slug under the context namespace 0d8937ce-eb24-52d2-9532-39ea299f888b (a constant; see Context terms).
Worked example
The line
[-] Call the plumber !2 +phone @2026-10-03T09:00 =plumber #01a0faa2-0000-7000-8000-000000000001
projects as follows, with :a the action and :phone its context; the blank-node labels are only for reading.
:a a obo:IAO_0000007 ; rdfs:label "Call the plumber" ;
obo:BFO_0000178 _:intent . # @: planned for 09:00
_:intent a cco:ont00000965 .
_:intent-value a cco:ont00000253 ; obo:BFO_0000101 _:intent ;
cco:ont00001767 "2026-10-03T09:00:00"^^xsd:dateTime .
_:priority a cco:ont00000369 ; cco:ont00001811 :a .
_:priority-value a cco:ont00000253 ; obo:BFO_0000101 _:priority ; cco:ont00001773 2 .
_:phone a cco:ont00000127 ; obo:BFO_0000178 :a , _:phone-condition .
_:phone-condition a cco:ont00000853 ; cco:ont00001982 :phone .
:phone rdfs:label "phone" .
_:alias a cco:ont00000003 ; cco:ont00001916 :a . # designates
_:alias-value a cco:ont00000253 ; obo:BFO_0000101 _:alias ; cco:ont00001765 "plumber" .
_:act a cco:ont00000228 ; cco:ont00001920 :a .
_:status a cco:ont00000203 ; cco:ont00001868 _:act .
_:status-value a cco:ont00000253 ; obo:BFO_0000101 _:status ; cco:ont00001765 "in progress" .
With :2026-10-04 on the line, it would also carry a condition whose bearer holds "late from" and "2026-10-05T00:00:00Z"; its children would carry the same one unless they had an earlier deadline of their own.
Times
A window bound is the effective instant from the application graph: has datetime value (cco:ont00001767), an xsd:dateTime with an offset, resolved in the viewer’s zone (convention 8). Every other time is as written: an intent, a completion or cancellation time and dcterms:created. A date and time is has datetime value, an xsd:dateTime in the form YYYY-MM-DDThh:mm:ss, with the offset or Z only if the file wrote one; a date alone is has date value (cco:ont00001771), an xsd:date.
Conformance
examples/conformance/graph/ holds the oracle: a workspace and the exact graphs it projects to.
- Application graph. A conforming implementation, projecting in the UTC zone, produces a graph isomorphic to
expected-app.ttl.schemas/app.shapes.ttlholds its SHACL shapes, including that the derived terms agree with the written ones;invalid-app/holds a graph per rule that must fail on exactly the shape it names. - CCO graph.
expected.ttlis the same workspace’s meaning.schemas/graph.shapes.ttlholds its SHACL shapes, validated without inference;invalid/holds graphs that must each fail on one named shape andwarning/one that must pass with only a warning. Merged with the ontology, it must reason consistent.
Habit identity, state and slot examples are in examples/conformance/habits/; objective states remain uncovered. The Habit fixture includes application-to-CCO mapping checks.
Determinism
For a given workspace and viewer’s zone, a given serialization is byte-deterministic: node order is stable and documented, and IRIs follow the rules above. Written values never depend on the machine. The derived instants app:notBefore and app:lateFrom depend on the viewer’s zone wherever a time was written without an offset or a bound is a date, and so does app:durationMinutes for a block that crosses a change of offset; a graph exported from one zone and read in another keeps the instants of the zone that projected it.
Optional Local SPARQL Evaluation
This section is non-normative to the dataset: running SPARQL locally over exactly the dataset defined above, as an optional convenience. The evaluator loads only ClearHead’s generated dataset into an ephemeral in-memory store, runs one query, and exits. Saved queries are ordinary .sparql files that MUST also run unchanged in independent SPARQL tooling.
Union Default Graph
When a query declares no dataset of its own (no FROM or FROM NAMED), the evaluator’s default graph is the union of all named graphs: triple patterns without a GRAPH clause match across every workspace, so the same query works over one workspace or several. Use GRAPH ?g only when a query must expose or constrain the source workspace.
The union is a set, as SPARQL defines a graph: a triple asserted in several workspace graphs, such as the label of a context node they share, matches once. A store’s built-in union mode may instead match it once per graph, so the default implementation copies every quad into the default graph when it builds the store. A test should build its store the way the evaluator does.
Source Boundary: Ontology vs Integration Profiles
The ontology stays source-agnostic; integration profiles such as .ics carry source-specific semantics. When actions are generated from an external schedule, implementations preserve the link through two optional fields, mapped in the ICS profile as:
occurrence.habit_id <- the native Habit's line UUID, published asapp:occurrenceOfthe Habit’s IRIoccurrence.occurrence_key <- the canonical original slot, published asapp:slot(xsd:string); transport UID and frames stay in sidecars
ClearHead Ontology
Current: V5 (5.0.0-draft), on CCO v2.2 and IAO. Folded into the specification on 2026-10-04 from the former ontology repository, with its history (platform Decision 50).
What ClearHead’s data means, stated in standard terms. V5 defines no terms of its own: objectives and plans are CCO, an action is IAO’s action specification, and conditions, status, priority and records are CCO patterns. The application vocabulary (../ontology.md) is what implementations publish; this directory is its meaning.
- domain.md: the domain in plain words, its competency questions, and the standard term for each part.
- DECISIONS.md: the choices behind it, with alternatives rejected.
Layout
| Path | What |
|---|---|
clearhead.ttl | The ontology header: imports, no terms. |
imports/ | CCO v2.2 and an IAO module, pinned by checksum. |
examples/ | Real plans written in the standard terms. |
queries/ | One robot query per competency question, with its expected answer in expected/. |
verify/ | Must-never-happen checks (every action belongs to a plan, every plan names an objective). |
mapping/ | One SPARQL CONSTRUCT per structure, from the application graph to these terms (Decision 50). |
unmapped.ttl | Every application term the mapping does not read, and why. |
Testing
Needs ROBOT and Java. The specification stays inert data: the platform’s scripts/validate-pinned runs this gate, and scripts/check-graph-shapes.py runs the mapping against the graph fixture.
make -C ontology test # merge, reason with HermiT, verify, check the competency answers, lint
make -C ontology answers # accept the current answers as expected, after reading the diff
make -C ontology imports # re-fetch the pinned CCO and IAO; fails if the bytes changed
Each answer in build/*.csv must match queries/expected/, so a question that answers wrong or empty fails.
License
MIT, as the whole specification: see its license section, which also credits the imports’ own licenses.
The ClearHead Domain
What ClearHead’s data is about, in plain words, and the standard terms that say it. The choices behind it, with the alternatives rejected, are in DECISIONS.md. The examples and checks that prove it are in v5/.
Principle
The system holds only information: plans, objectives, and records of what happened. The acts, events and states they are about exist, or fail to, in the world. A plan exists whether or not anyone ever carries it out.
Competency questions
The model must answer these, from the human’s own words. Each is a robot query in queries/, run by make -C ontology test over the examples.
- What do I need to do to complete my weekly review?
- Which steps depend on other steps for my objective to come to fruition?
- Which steps can I do within my current context, energy and priorities?
- How do I define done for my objectives, and how do I keep track of my plans and their steps?
- Which plans go toward a given objective?
- Did we fulfil those plans? If not, why not?
- What other details does the plan need to succeed?
- What are the risks, dependencies and supporting materials for this objective?
The domain
- Objective: a state someone wants to be true. Some are achieved once (get a degree, file taxes); some are maintained and never finish (inbox stays near empty).
- Plan: aims at an objective and contains actions. Without an objective it is not a plan; without actions it is a plan still being drafted.
- Action: prescribes one thing to do; the word means the prescription, never the doing. Actions contain actions, and every action is part of some plan. Splitting stops when whoever does it can do it without further planning, so the right depth depends on the doer.
- Conditions: an action may be prescribed given a condition: what it waits on (another action done, or something outside such as a reply), where or with what it can be done (its context), and the energy it calls for.
- Record: information that something happened: who acted, when, the outcome, and why it fell short. Status is a record too.
- Area of focus: a plan whose objective is maintained (“keep food in the house”). Not a separate kind of thing.
- Values statement: what objectives answer to (“live with integrity”). Never achieved, only reviewed.
- Weekly review: a recurring plan whose actions review the other plans: judging maintained objectives and values, and finding plans whose actions no longer lead to their objective.
Distinctions to keep
- Fulfilling a plan is not achieving its objective. When every action is done and the objective is not met, either the objective has no clear done-condition or the actions were the wrong ones. Achievement is confirmed by an agent, never derived (Decision 5).
- Planning done is not work done. One is the status of the act of planning, the other the status of the planned acts.
- The doer’s situation is not the action’s requirement. Current energy and whereabouts belong to the question being asked; the action states only what it calls for.
- A plan is sufficient when someone else could carry it out from what it holds: objective and done-condition, actions, risks, dependencies, materials.
- Context is a condition, not a container. “Errands” says where an action can be done; “buy milk” is done in the errands context for the plan “keep food in the house”. The information a plan carries is its supporting material, never its context.
- A rate is a plan, not an objective. “Run three times a week” prescribes acts; its objective is a state such as being fit.
Standard terms
Everything is CCO v2.2 or BFO, plus one IAO term. ClearHead defines no terms of its own (Decision 1). CCO IRIs are opaque, so the label is given beside each; cco: is https://www.commoncoreontologies.org/, obo: is http://purl.obolibrary.org/obo/.
| Domain | Term | Pattern |
|---|---|---|
| Objective | Objective cco:ont00000476 | A maintained objective prescribes a stasis. |
| Plan | Plan cco:ont00000974 | has continuant part (obo:BFO_0000178) its objective and its actions. |
| Action | action specification obo:IAO_0000007 | has continuant part its sub-actions. Belonging to a plan is a robot verify check, not an axiom. |
| Waiting, context, energy | Performance Specification cco:ont00000127 | Has as parts the action and a Descriptive ICE (cco:ont00000853) that describes (cco:ont00001982) the condition: an awaited action, a site (obo:BFO_0000029) or a quality (obo:BFO_0000019). |
| Progress (in progress, completed) | Event Status Nominal ICE cco:ont00000203 | is a nominal measurement of (cco:ont00001868) the act; its value is the text on an Information Bearing Entity (cco:ont00000253) that is carrier of it. Not started is the absence of any status. |
| Cancelled | Nominal Measurement ICE cco:ont00000293 | Measures the action itself, since no act exists (Decision 4). The reason is a Descriptive ICE that is about (cco:ont00001808) that measurement. |
| Objective achieved | Nominal Measurement ICE cco:ont00000293 | Measures the objective, confirmed by an agent (Decision 5). |
| Priority | Priority Measurement ICE cco:ont00000369 | is an ordinal measurement of (cco:ont00001811) the action; integer value on a bearer, 1 first. |
| What happened | Planned Act cco:ont00000228, Act of Planning cco:ont00000511 | prescribed by (cco:ont00001920) the action or plan, has agent (cco:ont00001833) who acted. |
| Why it fell short | Descriptive ICE | is about the act. |
| Risk | Predictive ICE cco:ont00000626 | is about the objective or plan. |
| Supporting material | Descriptive ICE | is about the plan or objective; a link is the URI value (cco:ont00001768) on its bearer. |
| Agent | Agent cco:ont00001017, Person cco:ont00001262 | An AI agent is the running machine (Decision 3). |
| Values statement | BCIO personal value BCIO_006063 | A disposition in the person; the statement is about it. Not imported yet: it arrives with the habit work. |
| Recurrence | none | A recurring action prescribes many acts; the rule is iCal RRULE, owned by the specification (Decision 6). |
| Time | Temporal Interval / Instant | The act occupies temporal region. |
Known stretch: a wait’s condition describes the awaited action specification, standing in for its act, which may not exist yet.
Upstream watch
Checked 2026-09-30 against the CCO milestones. Re-check when CCO 3.0 is tagged; CCO’s board recommends waiting for 4.0 before updating.
- Stable through 3.0 and 4.0: Plan, Objective, Planned Act, Act of Planning, Act of Measuring, prescribes, is about, Event Status, Stasis, Predictive ICE, Performance Specification. Everything above leans on these.
- In flux in 3.0: information and its carriers (#875, #593, #682, #596) and QUDT replacing CCO units (#307). Records are therefore Descriptive ICEs
is aboutthe act, not CCO Report. Priority Scale may move from Descriptive to Directive (#147); cosmetic for us. - Wanted from 3.0: the Information Structure Entity draft (#949) separates how information is structured from what it says. If adopted, the specification’s formats (lines, documents, calendar entries) could be stated as Information Structures in CCO’s own terms.
- Read axioms, not prose: some CCO definitions cite classes that no longer exist (“Directive Information Content Entity” in Planned Act, “Intentional Acts” in Plan).
Ontology decisions
Decisions about the ontology’s meaning (the former ontology repository’s log, folded in with Decision 50). Decisions that span repositories live in the platform’s docs/DECISIONS.md. Each entry states the choice, the alternatives rejected, and the trade-off accepted. The domain they shape, and its standard terms, is in domain.md.
Decision 6: Values and Recurrence Need No Terms of Their Own
Decided 2026-10-01 by the orchestrator, from the human’s standard-terms principle (Decision 1). A value is a disposition in the person (BCIO personal value, BCIO_006063), like a habit, and a values statement is an information entity that is about it. Recurrence is not an ontology entity: a recurring action prescribes many acts instead of one (CCO’s Plan prescribes “some set of intended acts”), a rate-like recurrence prescribes a CCO Frequency, and the calendar rule saying which intervals is iCal RRULE (RFC 5545), owned by the specification.
Alternatives rejected: a ClearHead Values Statement class; a recurrence class (no BFO-family ontology has one, and iCal is already the standard for the rule).
Trade-off accepted: recurring work is only fully understood with the specification’s iCal mapping beside the ontology.
Decision 5: Objectives Have State, Confirmed by an Agent
Decided 2026-10-01 by the human. An objective has its own state, as plans and actions do, and none is derived from another. Whether an objective is achieved is confirmed by an agent and recorded as the objective’s state: a Nominal Measurement ICE that is a nominal measurement of the objective, the same pattern as a cancelled action (Decision 4). Where an objective has a real measure (“on-time completion over 90% across three months”), the measurement is evidence the agent can confirm from; most objectives have none, and the agent’s confirmation is all there is.
Alternatives rejected: requiring measurable (SMART) objectives; deriving achievement from the state of the objective’s plans.
Trade-off accepted: the system never decides an objective is achieved on its own; someone has to say so.
Decision 4: Cancelled Is a State; Deleted Is Absence
Decided 2026-09-30 by the human. A dropped action is cancelled: “we are no longer doing this”, kept in the data with that state. A deleted action is out of the dataset entirely and leaves no record.
There are two kinds of state, measuring different things. Commitment states (cancelled) classify the action itself: a Nominal Measurement ICE that is a nominal measurement of the action, since no act exists to measure. Progress states (in progress, completed) are Event Status measurements of the act the action prescribes. Not started is the absence of either. The reason an action was cancelled is a Descriptive ICE that is about the cancellation; it cannot be a part of it, because CCO infers a descriptive whole with a descriptive part to be a Performance Specification.
Alternatives rejected: cancelled as an Event Status (there is no act for it to measure); a separate decision record as the only trace of cancelling (the human treats cancelled as a state).
Trade-off accepted: a state shown to the user is derived from two kinds of record rather than read from one field.
Decision 3: An AI Agent Is the Machine Running It
Decided 2026-09-30. An AI agent is a cco:Agent: the running machine, bearing an Agent Capability. The model is part of it in two senses: the copy of the weights in memory is a material part of the machine, and the model’s content is information the machine concretizes and acts on, as a person concretizes a plan.
Alternatives rejected: treating the model or the software as the agent (an Agent is a material entity in CCO; software is information); a ClearHead-specific agent class.
Trade-off accepted: “the agent” in records means a machine running a harness and model, so two runs of the same model on different machines are different agents.
Decision 2: Objectives, Plans and Actions
Decided 2026-09-30, from the human’s competency questions.
- An objective is a cco:Objective: a state someone wants, achieved once or maintained.
- A plan is a cco:Plan and names its objective as a part. Without an objective it is not a plan; without actions it is a plan still being drafted. An area of focus is a plan whose objective is maintained (“keep food in the house”).
- An action is an IAO action specification (IAO_0000007): information prescribing one act, never the act itself. Every action is part of a plan, directly or through other actions, even where no file names that plan: the specification’s workspace layout guarantees every workspace exactly one root charter, whose
next.actionsholds any action not filed elsewhere. An action with an objective of its own and actions of its own is also a plan, by the definition above; an action without one is only an action specification. - Waiting, context and energy are CCO Performance Specifications: an action prescribed given a condition, with a descriptive part that
describesthe condition (CCO’s owndescribes conditionpattern). IAO’s conditional specification was tried first; the reasoner classified every one as a Performance Specification, so CCO’s term is used. - What happened is never stored on a plan or action: acts are reached only through records about them (status, outcome, who acted).
Alternatives rejected: a ClearHead Step class (IAO already has action specification); every action a cco:Plan (most actions have no objective of their own); actions outside any plan (the root charter always contains them); areas of focus as roles holding objective-less actions (“errands” turned out to be a GTD context, not a container); a waits on relation of our own, and IAO’s conditional specification (both replaced by Performance Specifications without changing any competency answer).
Trade-off accepted: each wait costs a Performance Specification and a condition description instead of one edge; the file formats keep their compact syntax and the spec maps it to this structure.
Decision 1: Standard Terms Only, Tested With ROBOT
Decided 2026-09-30. This repository holds meaning, built from existing BFO-family terms: CCO v2.2 as is, plus IAO terms CCO lacks, pulled in as pinned MIREOT modules. A term of our own is minted only when a search of CCO, IAO and OBO finds nothing, and nothing is ever asserted about another ontology’s terms; constraints we want on them are robot verify checks over data. ROBOT is the only test tool: reason over the ontology plus examples, verify must-never-happen queries, and answer the competency questions with robot query.
Alternatives rejected: a ClearHead vocabulary that re-describes CCO terms in place (v4 annotated cco:Plan as “a recurrence prescription”, and its examples were inconsistent under a reasoner without any check noticing); importing all of IAO (two full information hierarchies for two terms); Python tests with pyshacl (they check shape, not meaning).
Trade-off accepted: IAO’s terms sit beside CCO’s under BFO rather than inside CCO’s information hierarchy, so queries over “all CCO information entities” must also ask for them.
iCalendar plans
title: iCalendar Plan projection specification description: VEVENT projections of Actions and Habits, fields and recurrence identity categories: Reference
iCalendar Plan projection specification
This specification defines RFC 5545 projections in each workspace’s <data_root>/plans/ vdir. The vdir is the complete integration boundary. CalDAV, vdirsyncer, Syncthing, Git, a mounted filesystem, or no transport may sit behind it. ClearHead does not depend on server accounts, hrefs, ETags or vendor metadata.
Actions are native work in ordinary .actions files. Habits are native recurring prescriptions in <charter>.habits.actions. A one-off Plan is not another domain entity: it projects an Action’s @ block. A recurring Plan projects a Habit. An unscheduled Action has no Plan. See Action syntax, workspace layout and process.
File location and discovery
Each resource is one VCALENDAR in plans/<charter-scope>/<resource>.ics, containing a VEVENT master and any same-UID RECURRENCE-ID overrides. ClearHead emits <uid>.ics; readers identify the resource by UID, not filename. Transport-selected filenames are preserved. Duplicate master identities, including mixed component kinds, are errors, never traversal-order winners.
Collection ownership follows the charter’s canonical workspace anchor, not its alias, title or an arbitrary next.actions basename. See Workspace.
VEVENT-only integration
Plans use VEVENT only.
A component has UID, SUMMARY and DTSTART; optional DTEND (or imported DURATION), DESCRIPTION, RRULE, RDATE, EXDATE and occurrence overrides. Missing required fields and duplicate identities are actionable errors local to the resource; unrelated files continue.
The calendar shows the @ block only. It is half-open: a DATE DTEND is the day after the last included date written in @; a time end is the written instant. : windows, lifecycle state, priority, contexts, hierarchy and dependencies stay local. Children are template steps, not independently recurring components.
Time frames (UTC, floating, all-day DATE and IANA TZID) are preserved. Unknown/custom zones are not interpreted as the machine’s local zone. Regeneration must preserve RDATE, EXDATE, time frames, overrides awaiting materialization, alarms, unrecognized properties, extensions, calendar metadata, original UID and transport-selected path. These facts must survive loss of reconstructible local state.
Description directives
Leading key: value lines are directives until a blank or non-directive line. template: <name> binds a named template. Directives are distinct from the human description; calendar edits must not silently turn a directive into ordinary prose. Inline Habit children win over a named binding, with a warning.
One-off Plans
A scheduled, non-recurring Action realizes exactly one Plan. ClearHead-authored resources use the native Action UUID as UID. A genuinely new calendar-authored one-off keeps its arbitrary external UID and gets an independent native UUID. Transport identity is never native identity. Scheduling and calendar-edit outcomes are defined in Process.
Habits and occurrence identity
A Habit’s native id is its line’s #uuid; it is not derived from UID. Each Habit projects to one recurring VEVENT. Moving an occurrence changes DTSTART, never the original slot in RECURRENCE-ID. Series and occurrence edit outcomes are defined in Process.
Canonical slot keys (slot-key-zone)
Keys are ASCII strings, independent of the viewer or device zone. Seconds are always present. Equivalent lexical precision normalizes to seconds; nonzero fractional seconds retain their value without trailing zeroes. The prefix distinguishes value types:
| Frame | Original slot | Canonical key |
|---|---|---|
| DATE | 20261026 | D:2026-10-26 |
| Floating | 20261026T090000 | F:2026-10-26T09:00:00 |
| UTC/offset | 2026-10-26T09:00:00-07:00 | U:2026-10-26T16:00:00Z |
| TZID | TZID=America/Los_Angeles:20261026T090000 | U:2026-10-26T16:00:00Z |
For TZID slots, resolve in the series zone using RFC 5545 §3.3.5 (first occurrence in a fold, pre-gap offset for a nonexistent local time), not the host’s zone. Preserve the frame separately for future expansion. In Los Angeles the fold slot 2026-11-01T01:30:00 keys as U:2026-11-01T08:30:00Z; the gap slot 2026-03-08T02:30:00 keys as U:2026-03-08T10:30:00Z. Devices in UTC, Los Angeles and Tokyo compute all these same keys. DATE and floating keys are never converted to UTC.
The native occurrence id is UUIDv5(Habit UUID, "occurrence/" + key). A stamped step id is UUIDv5(occurrence UUID, "step/" + template-step UUID), with lowercase hyphenated step UUID text. Template-step UUIDs are persisted before stamping: renaming or reordering a step never changes its id; a deliberately new step gets a new UUID. Derived ids are persisted on the generated lines. app:slot is the canonical key as xsd:string, not a viewer-resolved xsd:dateTime.
Transport occurrence addresses remain (UID, RECURRENCE-ID). The durable native link is (Habit UUID, canonical slot), including for history after a transport UID replacement. These are different addresses of the same occurrence, not interchangeable identity inputs.
Field authority
Name (SUMMARY), human description (DESCRIPTION), planned start/end (DTSTART/DTEND), recurrence and exceptions are editable from either side. Action/Habit state, completion, priority, contexts, hierarchy, dependencies and : windows are not calendar-authoritative.
For conflict, kind-change, generation and history outcomes, see Process.
Observability Specification
Version: 1.0.0 Status: Draft
Purpose
This specification defines observability conventions for ClearHead tooling. It covers semantic events, structured logging, and debugging telemetry.
Observability is for:
- Debugging system behavior (“why is this action in this state?”)
- Property change history (“when did priority change from 2 to 1?”)
- Operational analytics (completion velocity, patterns over time)
- Distributed tracing (sync operations, cross-device coordination)
Observability is NOT for:
- Current state (that’s the domain data)
- Habit occurrences (authoritative Actions in
.actionsand.completed.actions; definitions in.habits.actions) - Sync coordination (that’s git)
Relationship to Other Concerns
Git → Sync, version history, conflict resolution
Domain Model → Current semantic state (charters, actions, plans)
DSL Files (.actions, .md) → Human-readable projections, queryable
Observability (this) → Debugging, analytics, audit trail
These are complementary. Git tracks file-level history. Observability tracks semantic history (what those file changes meant in domain terms).
Framework
ClearHead uses OpenTelemetry for observability:
- Standard format — Wide ecosystem support (Jaeger, Prometheus, Grafana)
- Structured logs — Semantic events with typed fields
- Offline-first — Local file export, aggregate later
Storage Location
Telemetry is stored in XDG state directory (machine-specific, not synced):
- Linux/macOS:
~/.local/state/clearhead/telemetry/(or$XDG_STATE_HOME/clearhead/telemetry/) - Windows:
%LOCALAPPDATA%\clearhead\state\telemetry\
File Format
Logs are stored as newline-delimited JSON (NDJSON) for easy parsing with DuckDB, jq, or standard tools:
telemetry/
├── events-2026-01.ndjson
├── events-2026-02.ndjson
└── ...
Files rotate monthly by default. Configurable via settings.
Semantic Events
Events are domain-specific and use consistent field naming.
Common Fields
All events include:
| Field | Type | Description |
|---|---|---|
timestamp | ISO 8601 | When the event occurred |
event | string | Event type identifier |
tool | string | Emitting tool (cli, lsp, sync) |
action_uuid | string | Related action UUID (if applicable) |
Action Lifecycle Events
| Event | When Emitted | Additional Fields |
|---|---|---|
action_created | New plan added | name, file_path |
action_completed | State → completed | name, completed_at |
action_cancelled | State → cancelled | name, reason (optional) |
action_started | State → in_progress | name |
action_blocked | State → blocked | name, reason (optional) |
action_restarted | State → new | name, reason (optional) |
action_archived | Action moved to archive | name, archive_file |
action_deleted | Action removed from file | name |
Property Change Events
| Event | When Emitted | Additional Fields |
|---|---|---|
priority_changed | Priority modified | old_priority, new_priority |
due_date_changed | Do date modified | old_date, new_date |
name_changed | Name modified | old_name, new_name |
context_added | Context tag added | context |
context_removed | Context tag removed | context |
Habit Events
| Event | When Emitted | Additional Fields |
|---|---|---|
instance_generated | Arrived slot durably stamped | habit_uuid, slot, action_uuid |
instance_completed | Occurrence completed | habit_uuid, slot, action_uuid, completed_date |
instance_skipped | User cancels an occurrence or an explicit exclusion skips an unstamped slot | habit_uuid, slot, reason |
habit_edited | Native Habit modified | habit_uuid, fields_changed |
habit_completed | Whole Habit completed | habit_uuid |
converted_to_habit | Kind-change proposal accepted | habit_uuid, converted_from (same native UUID) |
habit_catchup_pending | Bounded generation has remaining arrived slots | habit_uuid, resume_after |
calendar_link_held | Replacement relationship awaits explicit confirmation | uid, reason |
A missed slot is not a skip. Retry/no-op stamping emits no second generation event. Native Habit identity and canonical slot survive transport UID changes. Instance history belongs to Actions and archives, not telemetry.
Sync Events
Sync events are deferred to the future sync server implementation. Git is the current sync mechanism; file-level history is available via
git log. These event types are reserved for when a distributed sync server is introduced.
Semantic Patch / Projection Events
These events trace how a named semantic operation becomes a domain model change and how that change is projected to files. They are especially useful for debugging why a file ended up in a particular state.
| Event | When Emitted | Additional Fields |
|---|---|---|
patch_derived | A semantic change set is produced by a named operation with resolved targets | operation, patch_id, operation_count |
patch_applied | A semantic change set is applied to the domain model | patch_id, applied_count, skipped_count, reason (optional) |
projection_written | A projected DSL file is written from domain model state | file_path, bytes_written, reason (e.g., on_save, manual_apply) |
Correlation: Implementations SHOULD correlate patch_* events using tracing identifiers (e.g., OpenTelemetry trace/span IDs) so operators can answer: “what operation was requested, what change set was derived, what was applied, what was projected”.
System Events
| Event | When Emitted | Additional Fields |
|---|---|---|
workspace_opened | Workspace loaded | path, action_count |
file_parsed | Actions file parsed | file_path, action_count, parse_time_ms |
lsp_started | LSP server started | port (if applicable) |
Retention
Default retention: 1 year. Older files can be:
- Deleted automatically (if configured)
- Archived to cold storage
- Aggregated into summary statistics
Telemetry settings can be aggregated via a sync server but that is not required and up to implementors and configuration
See Also
- Process — Workflow and action lifecycle
- Configuration — Settings including telemetry options
Process Overview
Our fundamental unit of measurement is lists of actions.
Therefore, the entire system can be thought of as no more or less than a set of interconnected lists of actions.
This process covers the workflow to manage the state of said actions as they move through the system.
This process is built around the human-editable Actions File Format. Implementations may project those facts into the canonical Action JSON Schema, RDF, tables, or other presentations without making those projections a second workspace authority.
The process can be adapted to different implementation methods and delivery backends.
Capture
Like GTD, we can always start our actions in the “Inbox” whether that be a file, a binary format, or a physical tray a core piece of the system is the idea of an inbox where all the new stuff is aggregated.
Normally, it is assumed that people will be writing to the root charter’s next.actions file which you can read more about in the Workspace specification.
Remember, we arent putting all the details in yet, just get it out of your head and into the inbox.
5 Minute Rule
The 5 minute rule answers that annoying question “how do i know when something is too small for the inbox?”. the answer is “when it takes you longer to write it down than to do it”.
For most people, this can be ~5 minutes or less. so, if you know an action will take less than 5 minutes, and you CAN do it right now, just do it.
It seems small, but this core insight is one of the most powerful ways to get seemingly small things done that can have major impact while making the process of maintaining the list easier.
List Size
The 5 minute rule has a more subtle benefit. Its important to understand that as your action list grows, so does the sophistication needed to manage it.
Therefore, discipline is required to keep the list manageable and the 5 minute rule is a key part of that.
Clarify
Its also where the really hard work happens of deciding what ACTIONS need to be done to get to an intended outcome.
In particular, we want to have a viscious focus on writing down the next physical action that needs to be done to move something forward.
In many ways, this is the most important, and most difficult part of the process but is also the part that makes the system save more work than it costs as this allows us to do our thinking ahead-of-time such that by the time we get to doing the work, we already know exactly what to do and just have a list of next actions to follow.
This is also where we link our actions to the proper research material, next-step links and really CLARIFYING what is needed to move forward
We should also figure out what actions are indepedent and dependent, making sure to mark actions with dependendent actions as we work through the list
Another important consideration is the addition of tags as context for these actions so that we can filter down based on the context this action must be done within
Timeframes and Dates
While this system supports explicit time-blocking, scheduling hard chunks on the calendar is often overwhelming and requires more knowledge of the future than is available. Undated Actions should therefore remain normal and rely on priority and context when no calendar commitment demands attention.
When timing constraints are real, they live in the Action’s due window (:): a
deadline, optionally with a lower bound before which it cannot be done. The do
date (@) is separate: when we intend to work it, which bounds nothing. An
Action hierarchy composes windows by intersection: the effective window opens at
the latest lower bound on the Action or any ancestor, and closes at the earliest
deadline. The complete field and
coherence semantics are defined in
Actions File Format.
These effective values are query-time derivations. They do not justify writing inherited dates into descendants or manufacturing calendar commitments merely to make the projection easier to compute.
Organize
As we move through the inbox, we either complete actions, or move them to the appropriate action list
Like in other systems, its not about finishing everything necessarily its about putting them in the right place whether that be in the main workspace, a project folder, or even a someday/maybe list.
This is also usually where we start setting due/do dates on the calendar (yes, we have both).
Recurring work is defined as Habits in `.habits.actions`; `.ics` is the editable calendar projection, and deterministic occurrences live in ordinary `.actions`.
This is also where priorities can be assigned on the RFC 5545-aligned 1-9 scale (1 highest, 9 lowest); urgency and importance remain separate planning judgments rather than encoded quadrants.
On IDs
By the time we move the actions out of the inbox, it is recommended that each action is given a unique UUID so that it can be tracked throughout the system.
While optional, this is a key feature that enables powerful features from analytics, to logging, to cross-referencing actions between lists in a deterministic way.
It is assumed this will be done with tooling, either automatically or as a script, but it can also be done manually if needed.
Reflect
This one is either part 4 or 5 depending on your perspective.
But this is also where GTD aligns with Agile in their emphasis on _regular reflection and review_.
Both systems stress the importance of periodic review and periodically doing the three steps above at the appropriate times:
- Capture: Always happening, should be near effortless and be the first thing you do when something new comes up
- Clarify: Requires the most decision making of the other steps
- Sometimes you are working with others and clarifying actions can be a group activity
- Other times it is benficial to clarify actions as soon as you write them while the context is fresh
- other times the purpose of the inbox is important and it is a mark of discipline to NOT clarify actions on particularly thorny days and save this work for more dedicated review times.
- Organize: Like clarify, this often depends on the context but should be done in regular intervals
- If you do organize daily, restrict it to once or twice a day to avoid decision fatigue
- Weekly reviews are also a good default and when the bulk of the organizing is often done
- Monthly reviews can be good for full refactors of existing outcomes to ensure everything is still aligned with your goals
The real importance of reflection is that it is done _regularly_ such that it becomes a core _habit_ you build within your system. This means it must be deeply aligned with your workflow and schedule and will be a core part of how the workflow is built around you rather than the other way around.
While a good default is a weekly review, agile does this process bi-weekly on average which is normal for teams doing this process, while some individuals fine building a daily ritual to be core to how they keep aligned through the day.
On Analytics
This is where a robust system of review is crucial for success. We want to look back at what we have done while planning future intentions, so tooling may project the workspace into JSON, RDF, tables, or an external analytical store. These are read models over the authoritative workspace unless an explicit mutation contract says otherwise.
Blocked and Dependent Actions
One particular place where tooling makes this easier is the ability to identify when some actions may be blocked or depend upon one another which will help us identify bottlenecks in our workflow and ensure we are focusing on the right actions at the right time.
This process is difficult to do by hand with a file of strings, but trivially easy with even a simple database.
On Scheduling
This is also the stage where active use of the calendar bcomes key to managing the list of actions as reviewing both our upcoming and past intentions can often bring up new actions or remind us of key other actions we are trying to do
Engage
Any other point in time that you are not doing one of the above phases, you are in the "Engage" phase where you are using your system as a declarative action system where you simply look at your list of actions and complete them as time permits
Here we are embodying the core principles of deep work to keep us aligned on the next action we want to focus on, knowing that we have reviewed the relevant inboxes and have decided what can and should be done ahead of time.
Agenda View
Another core usecase for the system is being able to generate an "agenda view" of the actions that need to be done today or in the near future.
This is not simply actions that are due/do today, but also represents actions that have no open dependencies, are within the proper context you are in, and are the top priority actions you want to focus on. All of this requires not just a data system, but a robust one that is able to leverage the relationships between actions as a graph and do the hard work of filtering down to the right actions for you to focus on.
In many ways, this is the core "why" beind the whole system as we want to make generating, maintaining, and updating this list as easy and effortless as possible so that we are mostly focused on completing actions rather than managing the system itself.
If all goes well, this list should be where you spend the majority of your time as you work through your day.
This list will include recurring and one-off actions, as well as actions that have no due date but are of high priority of which can be done within the current context/timeframe.
Arhiving
Archival is a sparate activity from closure, a record can be closed however long we want to before it is "archived" and for some formats, the distinction isnt needed as much if the state is maintained within a database. however, for file-based interfaces it is often easier to move the closed records into some sort of "archive" for external storage and querying such that the whole graph can be queried at a a later time such as is outlined in the [workspace spec](./workspace.md)
Workflow
Now that we have covered the overarching stages, we want to get a bit more granular around the relationships between various properties around the actions and how they are meant to communicate our intent
Charters
Charters follow a fairly simple workflow as they are higher level than the plan and thus are expected to see less daily alteration. still, there is still some workflow to consider.
State
Charter state is a local fact governing whether its work stream is admitted for engagement:
New— defined but not yet admitted. This is the default whenstateis omitted from source.Active— eligible for engagement, provided every ancestor Charter is alsoActive.Blocked— cannot currently advance.Closed— finished and terminal.Cancelled— abandoned and terminal.
States never cascade implicitly. Changing a Charter’s state does not rewrite any
descendant Charter or Action. Effective eligibility is nevertheless inherited:
a Charter beneath a non-Active ancestor is not admitted even when its own local
state is Active.
Cross-level contradictions remain visible and are diagnosed rather than silently normalized:
- an
Activedescendant Charter orInProgressAction beneathNeworBlockedancestry is a warning; - an open descendant Charter or Action beneath
ClosedorCancelledancestry is a violation.
An Active Charter with no Actions is valid and does not require a warning.
Closure
Before closing or cancelling a Charter, its open descendant work should normally be completed, cancelled, moved, or otherwise reconciled. Implementations must not automatically complete or cancel descendants as an implicit consequence of the Charter transition. A separate explicit batch operation may be offered when the user deliberately requests cascading mutations.
Plans
Plans are VEVENT calendar projections of Action blocks and Habits. Native text owns the work; calendar edits can change the projected fields, not local workflow facts.
An unscheduled Action has no Plan. Assigning or changing @ creates or updates its one-off Plan; a calendar schedule edit updates @. Clearing @ removes the Plan without closing the Action. Deleting an established Plan unschedules the Action without deleting or cancelling it. An untracked snapshot’s absence alone is not evidence of deletion.
A genuinely new, unrelated VEVENT in an owned collection creates a scheduled, not-started Action in its owning Charter, using SUMMARY and human DESCRIPTION. Its arbitrary calendar UID is never mistaken for native Action identity.
Name, human description, planned start/end, recurrence and exceptions reconcile independently. Safe changes in one field continue while another conflicts. Agreeing values converge; differing values are presented for resolution, never silently decided by timestamps.
Habits
A Habit is a top-level line with R: in its charter’s .habits.actions. Any open state generates: [ ] not started, [-] in progress and [=] blocked. Only [x] completed and [_] cancelled stop generation, including catch-up; each records its closed date with %. Closing the Habit does not close any occurrence. There is no pausing, and [=] has no special generation meaning. To stop for a while, close the Habit and recreate it later.
An Action is materialized for every arrived slot, whether earlier occurrences are done or not. Missed occurrences stay open until individually completed or cancelled. Reads stay pure. Future slots are read-only projections, never editable Action rows. Catch-up may be incremental, but interruption or a limit on work per operation must not drop slots. Repeating generation must not duplicate active or archived occurrences.
Only the root recurs. Its children are a template forest stamped below each occurrence, not recurring calendar components. Alternatively, a leading template: <name> directive in its description names a workspace template. Children win when both are present, with a warning. Template steps have persisted, stable native UUIDs; title, order and path are not their identity.
A template does not recur and its steps do not depend on their ancestors. Generating from a template, by stamping an occurrence or applying it on demand, refuses a template with R: on any of its lines (lint E002) or a step whose < resolves to the Habit or another of the step’s ancestors (lint E009), naming each offending line’s file and line. A refused Habit generates nothing until it is fixed; its arrived slots then materialize as usual. Steps may still depend on sibling steps.
Each occurrence’s id derives from (native Habit id, original slot); step ids additionally derive from stable template-step ids. The canonical encoding is in the ICS specification. Repeated stamping, step rename and reorder do not duplicate steps. Template edits affect later stamps, never overwrite existing occurrence trees.
The : window is never synchronized. Each occurrence keeps the window’s offset from the repeated block, in that block’s time frame: date offsets in calendar days, floating offsets in wall time, zoned offsets in the series zone. Children then inherit effective windows normally.
Rule edits change subsequent expansion, preserving all existing active and archived occurrence facts and ids. Newly introduced arrived slots must still materialize; progress under a previous rule cannot hide them. Exclusions skip unmaterialized excluded slots, never silently delete materialized work. A completed or cancelled Habit makes no further occurrences, including catch-up.
Series time/rule edits target the Habit. RDATE, EXDATE and time frames are preserved with it. A single-occurrence edit, including a rename, targets only its Action; edits for an occurrence not yet materialized must survive until it exists. Rescheduling changes the matching RECURRENCE-ID override and the materialized Action, preserving the original slot as identity.
Kind changes and identity
Calendar changes between one-off and recurring work are never silently applied. The user must be able to review the resulting block and effects on children, dependencies, state, priority and contexts before authorizing the change.
- An accepted one-off → recurring change retains the Action’s native UUID as the Habit id; no duplicate old Action remains. The first occurrence has its own derived id, not the old Action’s id.
- An accepted recurring → one-off change ends the Habit. The newest open occurrence keeps its id and becomes the one-off Action; older open occurrences remain open for manual completion or cancellation. The resulting block must be visible, including when a calendar client returns to the original series start. If no open occurrence exists, the one-off Action keeps the Habit’s UUID, as a text kind change does and as a calendar keeps one UID when an event switches between recurring and single, so every device derives the same id.
- A text kind change moves the line between the ordinary actions file and habits file, adding or removing
R:and retaining its UUID. It does not adopt that line as a generated occurrence.
Transport UID replacement and this and following splits do not establish native identity. Retaining native identity after replacement requires an explicitly user-confirmed link, never automatic matching. Ambiguous relationships remain unresolved; a suspected replacement with no candidate stays held without creating a new entity until the user supplies a link. A possible match is not proof of identity.
Plans vs Actions
Plans and Actions are distinct, linked concerns:
- Plans live in
.icsas projections; native Habits and sidecars hold recurrence and occurrence deviations. - Actions live durably in
.actions; hierarchy, dependencies, and unmapped ClearHead workflow semantics remain local there. - Not every Action has a Plan; ad-hoc and intentionally unscheduled Actions are valid.
- VEVENT reconciles blocks, names, human descriptions, recurrence and exceptions field by field. State, completion, priority and contexts stay local; no peer silently wins conflicts.
- Kind changes require user authorization; native identity and existing history are preserved as described above.
See the workspace specification for file placement and archival, the iCalendar schedule specification for format and identity semantics, and the ontology for the Plan–Action relationship.
Actions
Actions will be the primary record type that people will interact with day-to-day and as such understanding their workflow is key
State
Action state records the lifecycle of one concrete act:
NotStarted— open and not presently underway; the default for a new Action.InProgress— presently underway. It is not another spelling of CharterActive.Blocked— open but unable to advance; explicit dependencies are preferred when they accurately identify the blocker.Completed— finished successfully and terminal.Cancelled— intentionally abandoned and terminal.
A common workflow is NotStarted -> InProgress -> Completed; blocked or
cancelled paths remain valid. State transitions are local facts and do not
implicitly mutate parent or child Actions.
Ready is derived and must not be stored as an Action state. A NotStarted
Action is ready only when:
- its owning Charter and every ancestor Charter are
Active; - every predecessor is satisfied (
CompletedorCancelled); and - applicable schedule and context constraints permit execution.
A trusted next-work projection surfaces admitted InProgress Actions before
ready NotStarted Actions. Contradictory InProgress work beneath non-admitted
Charter ancestry is reported as a coherence finding rather than silently treated
as ready.
On Closure
Closure and archival are separate transitions. Completing or cancelling an Action changes that concrete Action’s lifecycle state; archival then moves the terminal record into durable history.
A one-off Plan is not a second lifecycle object. Action completion remains local. Archiving an occurrence snapshots its native Habit id, transport link and canonical slot into durable metadata. Closure does not advance a single live token: every arrived slot is independent. Future read-only projections are not Actions and are never archived.
On Child Actions
Parent and child Action states remain independently asserted; neither direction cascades implicitly. Tooling may derive facts such as “subtree complete” or omit an open container from a next-work projection while an executable descendant exists, but those projections do not change the parent’s stored state.
A terminal parent with open descendants is contradictory and should be reported for deliberate reconciliation. An explicit command may offer a reviewed batch transition, but merely completing or cancelling one Action must not rewrite its relatives.
Priority
Priority uses the RFC 5545 range directly: 1 is highest and 9 is lowest. An omitted priority means undefined. This direct scale preserves VTODO interoperability without a lossy conversion table.
Priority is ordering guidance, not an encoded Eisenhower quadrant. Urgency may be represented by dates and importance by the surrounding charter or objective. Work that no longer deserves attention should be explicitly cancelled rather than hidden behind a special priority value.
Engineering Process
The stages above describe how *users* move actions through the system. This section describes how *we* should move engineering next-actions through it, because the same discipline that keeps a personal list honest keeps a charter honest.
The Call-Site Sweep Done-Gate
A core capability is not done until every call site that duplicated it has been swept onto it, and a guard exists so the old pattern cannot silently reappear.
This was learned the expensive way on the core-seam charter (2026-07-11): several next-actions had been marked `[x]` with plausible, detailed descriptions of what "landed" — a precedence-bug fix, subtree-close semantics moved to core, a durability guard — and none of it existed anywhere in the repository. No commit, no stash, no other branch. One of them was a live user-facing bug marked fixed while still reachable through four different commands.
The pattern that let this happen: a capability got added to core, but the CLI's own call sites kept their inline, duplicate implementation next to it. Nothing forced convergence, so "the core function exists" was mistaken for "the capability is done." Two capabilities can coexist for a long time — the description alone can't tell you which one a caller actually goes through.
The done-gate this charter proposes, going forward:
1. **Implement the capability once**, in the layer that should own it (core, in the core-seam charter's case).
2. **Sweep every call site onto it.** Find each place the old inline/duplicate logic lived and delete it, not just add a new path beside it. If a caller can still reach the old code, the sweep is not done.
3. **Add a guard** — a test, a lint, a grep-check — that fails if the old pattern reappears. Not every capability needs one (a guard is proportional to how easy the old pattern is to reintroduce and how costly a regression would be), but if you needed to sweep it once, assume someone will reintroduce it by accident later.
4. **Verify the claim against the code, not the description**, before marking it done. A next-action's description is a claim about the world; `git log` and the source tree are the world. If you can't point at a commit and a diff that matches the description, it isn't done yet — write down what's actually true instead of what was planned.
Step 4 is the one that would have caught the 2026-07-11 gap immediately: none of the falsely-completed items had a matching commit. Checking is cheap; trusting a well-written description is what's expensive.
ClearHead Process Explanation
While the process specification is probably the most high-level document and covers the process in an abstract way, its important to explain how it connects to the other bits of guidance in the specifications.
In particular, the way to understand the process is as something that brings together most if not all of the concepts covered in the other documents to make an open, document-based process that tries to cover each topic orthogonally to give implementors specific guidance when they need
Context
For starters, the process is assumed to be a check that happens AFTER intial parsing according to the File Format specification. This means that any file being processed is already known to be valid according to the grammar.
As well as being after the Formatting phase, which means that any files being processed are also in a canonical format that tools can rely on to make certain assumptions about structure and layout. (or not!) all optional.
Now, linting can happen either before or after processing depending on the use case. For example, a linter could be used to check for issues before processing to prevent bad data from entering the system, or it could be used after processing to ensure that certain process level checks outlined in process are being followed.
Embracing Minimal Structure
In order to avoid stuffing implementors with design details, we instead leverage the filesystem itself for much of how we handle this process. for example, workspace conventions are used to determine which files are considered part of the process without needing to define complex structures within the files themselves.
All of this can be configured according to the configuration specification to allow people to control the process no matter what tool they are using, and implementors need only respect this shared configuration in order to allow users to move seamlessly between different tools.
Extra Features
While the core process is intentionally minimal, implementors are encouraged to add extra features on top of this that enable better user experiences and make the tools more powerful overall including:
- Observability features to allow users to track and monitor their actions over time while also allowing various tools to integrate with each other more easily as they can find the shared history of how a set of plans have changed over time.
- Optional synchronization mechanisms may keep workspace resources available across devices, but must preserve the authoritative plaintext and projection boundaries defined by the workspace and iCalendar specifications.
- the Ontology specification allows all of this to be implemented in a universal way such that different tools can understand and interoperate with each other more easily without needing explicit integration points built out for each pair of tools.
While none of these features are required, they allow much more of the analytical and collaborative use cases outlined in the process document
Data workflows: select semantically, act atomically
ClearHead keeps reading and writing as separate operations that compose through canonical identities and published JSON contracts.
- Read:
clearhead query …loads the authoritative plaintext workspace, asks Core for its deterministic RDF dataset, and optionally evaluates SPARQL in a fresh in-process store. - Write:
clearhead transactapplies an ordered, atomic batch of Action operations through Core’s mutation decisions and the native delivery adapter. - Contract:
transaction_requestandtransaction_result.
The RDF dataset and ephemeral query store are replaceable projections. Neither is a persistence layer or a mutation surface.
The loop
# Complete every unscheduled action the query surfaces, in one atomic batch.
clearhead query index unscheduled --format ids \
| jq -Rn '{operations: [inputs | {op: "complete-action", target: .}]}' \
| clearhead transact
The index family’s --format ids projection emits one canonical urn:uuid: per
line. transact accepts that spelling as an operation target, so selection does
not need a name-resolution or output-conversion shim.
For a human
Run the query alone first, then rehearse the mutation:
clearhead query index agenda
clearhead transact request.json --dry-run
clearhead transact request.json
A dry run validates and prepares the complete batch without writing.
For an agent
transact emits a schema-valid transaction_result: committed, dry-run, or
rejected, including the zero-based index of a failed operation. Rejection is
non-zero and leaves the authoritative workspace unchanged.
Query ownership
clearhead query owns the complete query surface:
rawandnamedevaluate standard SPARQL over Core’s canonical dataset;index,tree,graph, andchainadd query-family validation and presentation;showprints the selected SPARQL document;listreports available saved and built-in queries.
With the default sparql feature, evaluation uses a fresh in-memory Oxigraph
store for each invocation. The store is never persisted, federated, or exposed
as a service. A minimal CLI build omits the query engine entirely. Exported RDF
remains engine-independent and may be consumed by external SPARQL tooling.
Mutation boundary
Transactions express intent, not filesystem patches. Core prepares semantic
changes and host-neutral effects; clearhead-workspace-fs validates revisions
under the native lock and delivers the complete batch durably.
The initial transaction surface remains deliberately small:
- operations are
update-action,complete-action,cancel-action, andreopen-action; complete-actionandcancel-actionset only the named action’s state tocompletedorcancelledand stampcompleted_atin place. They do not cascade, detach parent links, or move lines to another file;reopen-actionsets only the named closed action tonot_startedand clearscompleted_atin place. It is allowed only in the active file and is refused for an archived action with anarchivederror naming the targetid, therootto unarchive first, and the originalquery(see the archived rejection);update-actionrefuses a closed target altogether, even for non-state edits, and refuses terminal state values; use the close or reopen operations instead;- all operations target one selected workspace;
- a failed operation rejects the entire batch.
Closed lines in the active file are ordinary records. Closing a parent does not close its children; W002 (closed parent with an open child) and W003 (open parent with all children closed) remain warnings, not mutation guards.
Only archive and unarchive transfer action lines between the active and completed files, always as a whole root tree (a root and everything below it). Archive requires a closed root whose entire tree is closed. Unarchive takes a root in the completed file and returns its whole tree without changing states. Either operation refuses a child target and names its root. Parent links inside an archived tree are retained; closing does not detach them.
For example, valid_reopen.json
reopens one closed action in the active file. Its descendants are unchanged, its
completion date is cleared, and only the active file is written. The
committed receipt and
dry-run preview likewise show
single-action closes: open_children lists the ids left open beneath the action
(one remains open in the committed example; none in the dry-run example), and no
completed file is written. Complete and cancel
receipts have no children count. Reopen receipts carry neither children nor
open_children; only delete receipts retain the descendant children count.
Single-item work should use the ordinary verbs. A transaction exists for edits that must succeed or fail together.
Understanding Whitespace in the ClearHead Ecosystem
For some languages, whitespace is syntactically significant. Python uses indentation to define code blocks, and YAML relies on spacing to denote structure. However, in the ClearHead ecosystem, whitespace is intentionally designed to be syntactically insignificant. This means that the presence or absence of spaces, tabs, or newlines does not affect the meaning of the code or data.
If one reviews the File Format specification, it becomes clear that explicit markers are used to define structure and meaning. This design choice simplifies parsing significantly, as parsers do not need to account for varying whitespace patterns.
This also means the specification if relatively liberal about what it will allow in the various structures such that its fine for an action to have a newline character in the middle of it
Another way to think about it is in phases, with the file format parsing phase being distinct from the formatting/linting phase, which itself is separate from the process phase.
Leveraging Parse Trees
While whitespace is not semantically significant, it IS important for human readability and we dont want to have people tinkering around with whitespace all day to make their perfect file.
To this end, formatters can leverage the parse tree generated during the parsing phase to apply consistent formatting rules. By operating on the parse tree, formatters can ensure that the structure of the code remains intact while applying desired formatting styles.
This works in tandem with linters which can provide feedback on non-whitespace style issues without being concerned about whitespace itself such as the order in which metadata appears or which metadata is available when
ClearHead Examples
This directory contains example .actions files demonstrating various features of the ClearHead format.
Basic Examples
- minimal.actions - Simplest possible action
- with_children.actions - Parent-child action hierarchy
- with_description.actions - Actions with descriptions
- with_priority.actions - Priority levels
- with_context.actions - Context tags
- with_do_date.actions - Scheduled (do) dates and times
- with_completed_date.actions - Completed actions
- with_story.actions - Actions belonging to projects/stories
- with_everything.actions - All optional fields demonstrated
New Features (v2.0)
- with_alias.actions - Action aliases for stable references (
=alias-name) - with_sequential.actions - Sequential children marker (
~) for ordered workflows - with_short_uuid.actions - Short UUID references (8 chars) for predecessors
- with_story_path.actions - Hierarchical story paths (
*work/clearhead/cli) - with_new_features.actions - Comprehensive example combining all new features
Scheduling Note
Recurring schedules are defined in .ics files. .actions examples in this directory represent actions (including generated occurrences), not schedule definitions.
Calendar Export
The export command converts actions with due dates into iCalendar (.ics) format for import into calendar applications. Only actions with @ (do_date_time) are included in the export.
Example Files
- calendar_export_example.actions - Comprehensive demonstration including:
- Multiple scheduled actions suitable for calendar export
- All action states (pending, in-progress, blocked, completed, cancelled)
- Priority mapping, categories, and descriptions
- Mixed work/personal planning examples
Example Usage
# Export all actions with dates to iCalendar format
clearhead export calendar_export_example.actions -o calendar.ics
# Export only open (pending/in-progress/blocked) actions
clearhead export calendar_export_example.actions --open-only -o calendar.ics
# Export to stdout for piping
clearhead export calendar_export_example.actions | less
# Export from stdin
cat calendar_export_example.actions | clearhead export > calendar.ics
Importing to Calendar Apps
Google Calendar:
- Export:
clearhead export inbox.actions -o calendar.ics - Go to Google Calendar → Settings → Import & Export
- Click “Select file from your computer” and choose
calendar.ics - Recurring events will automatically expand in your calendar
Apple Calendar:
- Export:
clearhead export inbox.actions -o calendar.ics - Double-click the
.icsfile - Choose which calendar to import into
Outlook:
- Export:
clearhead export inbox.actions -o calendar.ics - File → Open & Export → Import/Export
- Choose “Import an iCalendar (.ics) or vCalendar file”
Supported Features
The calendar export uses standalone VTODO components and supports:
- Scheduled times -
scheduled_atbecomesDTSTART - Due times -
due_datebecomesDUE - Descriptions - Action descriptions become VTODO descriptions
- Priority - ClearHead priority maps directly to RFC 5545
PRIORITY(1-9) - Categories - Context tags become standard
CATEGORIES - Status - Action state maps through VTODO
STATUS:[ ]NotStarted →NEEDS-ACTION[-]InProgress →IN-PROCESS[=]Blocked/Awaiting →NEEDS-ACTIONplusX-CLEARHEAD-STATUS:blocked[x]Completed →COMPLETED[_]Cancelled →CANCELLED
Example File
See calendar_export_example.actions for a comprehensive demonstration of calendar-exportable actions.
Test Files
- conformance/ - Semantic and byte-level conformance corpus, one scenario per fixture (
parse,diagnostics,archive,syntax); see conformance/README.md - formatting/ - Directory with formatting test cases
- linting/ - Directory with lint rule examples
Queries
The queries/ directory contains examples of SQL queries for filtering actions.
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.