Proposal: checkbox CLI commands for discovery, editing, and progress reporting (design in progress)

[DandyLyons]

Summary

Add a md-utils checkboxes command group for finding, checking, unchecking, and reporting on Markdown task-list items.

Status: preliminary design proposal. The design is not complete, and this issue is not a finalized implementation specification. The maintainer likes the design direction below. Command names, selection semantics, output contracts, and edge cases still need to be refined before implementation.

Proposed initial scope

Command	Purpose	Example
find	List checkboxes with file, line, state, and text	md-utils checkboxes find notes/ --unchecked
check	Mark selected checkboxes complete	md-utils checkboxes check TODO.md --line 12 --in-place
uncheck	Mark selected checkboxes incomplete	md-utils checkboxes uncheck TODO.md --all --in-place
stats	Report checked, unchecked, total, and completion percentage	md-utils checkboxes stats notes/ --by-file

Consider defaulting md-utils checkboxes to find. Reuse existing directory traversal and --in-place conventions.

All syntax in this issue is proposed, not currently implemented.

Proposed selection model

Share applicable selectors across commands:

• --checked / --unchecked: filter by state.
• --line 12: select by original file line number; repeatable and restricted to a single file.
• --text "Write tests": exact task-text match.
• --contains "tests": substring match.
• --section "Release checklist": scope to a heading and its subsections.

Different filters combine with AND. Editing requires a selector or explicit --all. Text selectors matching multiple tasks require --all to change every match. Clarify these semantics during design, particularly the interaction of --all with filters and no-op tasks.

# Discover unfinished release tasks
md-utils checkboxes find TODO.md --section "Release" --unchecked

# Preview the document with one task completed
md-utils checkboxes check TODO.md --text "Publish release"

# Save that change
md-utils checkboxes check TODO.md --text "Publish release" --in-place

# Reset a recurring checklist
md-utils checkboxes uncheck weekly.md --section "Weekly review" --all --in-place

# Export tasks for scripts or agents
md-utils checkboxes find notes/ --unchecked --format json

Proposed output

Human-readable discovery output:

TODO.md:12  [ ] Write tests
TODO.md:18  [x] Update documentation
notes/release.md:7  [ ] Publish release

JSON should include file path, line and column, checked state, task text, heading ancestry, and nesting depth. Finalize the schema, coordinate conventions, ordering, and multiline task representation before treating it as a stable contract.

For edits, print transformed Markdown for a single file unless --in-place is supplied. Support --dry-run to review changes across files. Multi-file output and partial-failure behavior remain open design questions.

Proposed behavior

• Recognize Markdown task-list items, including nested tasks, ordered lists, and tasks inside blockquotes.
• Treat [x] and [X] as checked; write [x] when checking.
• Ignore checkbox-looking text in code, frontmatter, and ordinary prose.
• Change only the checkbox marker, preserving indentation, wrapping, line endings, and surrounding content.
• Make check and uncheck idempotent: an already-correct task is a successful no-op.
• Leave parent and child states independent by default.

The main priorities are reliable selection, minimal source edits, and useful machine-readable output.

Additional ideas for later consideration

Idea	Value
assert --all-checked	Fail CI when a release or acceptance checklist has unfinished tasks; require --allow-empty to accept no tasks.
toggle	Useful for editor integrations, but unsuitable for retryable scripts because repeated execution reverses the result.
add --section … --text …	Append a task directly to a named checklist.
--children on edits	Explicitly check or uncheck a selected task's descendants.
reset	Discoverable shortcut for resetting recurring checklists.
archive	Move completed tasks to another section or file; defer until nested tasks and attached paragraphs are well defined.

Defer custom states such as [/] and [-] until a later release with explicit dialect support. These ideas are not commitments for the initial release.

Architecture direction

• MarkdownUtilitiesCore: discovery and source-preserving marker transformations.
• MarkdownUtilities: filesystem integration.
• md-utils: command handling and output.

Follow the project's parsing requirements, using the Parsing library for text parsing and evaluating the existing Markdown syntax infrastructure for structural recognition. Keep Core portable and cover behavior with Swift Testing.

Design work still needed

• Finalize initial scope, CLI names, defaults, and selector interactions.
• Define exact versus rendered task text, case sensitivity, and multiline matching.
• Resolve duplicate heading names and section selection ambiguity.
• Define no-match, ambiguous-match, and empty-input behavior and exit codes.
• Define multi-file previews, write failure reporting, and protection against stale selections.
• Specify task syntax boundaries, nested-list behavior, and source coordinate conventions.
• Finalize JSON and stats output, including zero-task completion reporting.
• Define implementation acceptance criteria and regression coverage once the design is settled.

This issue records the preferred direction for further design; it should not be interpreted as approval of a complete, frozen specification.