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 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

  1. Relaxed parsing, strict linting - Parser accepts most input, linter validates rigorously
  2. Non-destructive - Linters report issues, they don’t automatically fix semantic problems
  3. Configurable - Rules have severity levels (error, warning, info) and can be disabled
  4. Helpful - Messages guide users toward fixes with clear explanations
  5. Fast - Checks should be efficient enough for real-time editor integration
  6. 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.