Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help


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] Task rather than [x]Task
  • Space before each metadata field: Task !1 +tag #id rather than Task!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 every name/metadata field 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_text is 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_space directive 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.scm now 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