TRC-1003 - Concrete Syntax Tree Checkbox Splicing

Living Document Notice
Published 2026-09-17. The evolving architecture, revisions, and connected notes for this dispatch live in the Stax Digital Garden.

Concrete Syntax Tree Checkbox Splicing

Summary

Automated task tools often destroy file formatting, delete comments, and mangle whitespace when updating checkboxes. Trice employs lossless Concrete Syntax Tree (CST) token splicing based on the Rowan green-red tree architecture to mutate checklist states with zero trivia loss.

The Trivia Destruction Problem in AST Mutations

Standard Abstract Syntax Tree (AST) parsers strip non-semantic content: indentation spaces, trailing tabs, inline HTML comments, and blank lines are discarded during serialization. When a tool reads task.md, checks a box, and serializes it back to disk, the human formatting of the document is mangled:

-  * [ ] 2026-09-17: Run database migrations <!-- critical order -->
-
-  * [ ] Review query logs
+* [x] 2026-09-17: Run database migrations
+* [ ] Review query logs

For sovereign knowledge graphs intended to survive for decades, trivia loss is an unacceptable degradation of document integrity.

Rowan Green/Red Tree Architecture

Trice preserves 100% of formatting by parsing notes into a Concrete Syntax Tree (CST) using the Rowan library architecture. A CST represents every single byte of the source text, including comments and whitespace:

+-------------------------------------------------------------+
|                    Rowan CST Node Topology                  |
|                                                             |
|   Root (GreenNode)                                          |
|     ├── LinePrefix: "  * "                                  |
|     ├── CheckboxToken: "[ ]" <--- Spliced in place to "[x]"  |
|     ├── Whitespace: " "                                     |
|     ├── TaskText: "Run database migrations"                 |
|     └── InlineComment: "<!-- critical order -->"            |
+-------------------------------------------------------------+

Lossless Checkbox Mutation

When the user marks a subtask as completed, Trice targets the exact byte span of the checkbox token without re-serializing the surrounding document:

pub fn toggle_checkbox(source: &str, line_number: usize, new_char: char) -> String {
    let mut lines: Vec<&str> = source.lines().collect();
    if line_number < lines.len() {
        let target_line = lines[line_number];
        if let Some(pos) = target_line.find("[ ]") {
            let mut updated_line = target_line.to_string();
            updated_line.replace_range(pos + 1..pos + 2, &new_char.to_string());
            // Splice into document preserving exact newline characters
            return splice_document(&lines, line_number, &updated_line);
        }
    }
    source.to_string()
}

Extended Checkbox Semantics

Trice extends standard GitHub-flavored Markdown checkboxes to support intermediate states without violating markdown renderers:

Marker	Visual State	Semantic Meaning
- [ ]	Empty Box	Pending action item
- [x]	Checked Cross	Completed verified
- [/]	Forward Slash	In progress / partially complete
- [-]	Hyphen / Dash	Cancelled / deliberately dropped
- [?]	Question Mark	Requires clarification or research

Because these characters sit inside standard [ ] delimiters, third-party viewers render them gracefully as list items, while Trice’s CST engine extracts granular progress percentages.

---

• Directus Target: trice
• Garden Source Reference: MOC - Bosun PKM Tools, MOC - Fleet Operations
• Garden Source Reference: [TRC-1003 - Concrete Syntax Tree Checkbox Splicing](TRC-1003 - Concrete Syntax Tree Checkbox Splicing)