Add Markdown task and list commands

Author: brandonbloom

README.md

@@ -101,6 +101,10 @@ Porcelain commands infer the format from the file extension:
 | `section replace <path> <heading> <content>` | Replace the body under one Markdown heading. |
 | `section append <path> <heading> <content>` | Append a block fragment under one Markdown heading. |
 | `section prepend <path> <heading> <content>` | Prepend a block fragment under one Markdown heading. |
+| `task close <path> <text>` | Ensure a Markdown task is closed. |
+| `task open <path> <text>` | Ensure a Markdown task is open, creating it when a destination is addressed. |
+| `list add <path> <text>` | Add one Markdown list item. |
+| `task add <path> <text>` | Add one open Markdown task. |
 | `create <path> [<content>]` | Create a file with explicit or extension-aware default content. |
 | `move <src> <dst>` | Move a file path. |
 | `copy <src> <dst>` | Copy a file path. |
@@ -164,6 +168,15 @@ etch set journal/today.md heartbeat "ok" --section "## Status" --tail
 etch delete tasks/follow-up.md snooze --task "Send follow-up"
 ```
 
+Mutate Markdown tasks and lists:
+
+```sh
+etch task close tasks/follow-up.md "Send follow-up" --section "## Actions"
+etch task open tasks/follow-up.md "Review draft" --section "## Actions"
+etch list add tasks/follow-up.md "Capture launch note" --section "## Notes"
+etch task add tasks/follow-up.md "Send update" --section "## Actions"
+```
+
 Mutate a Markdown section:
 
 ```sh
@@ -263,6 +276,9 @@ missing JSONL targets are created as empty logs before appending.
 For Markdown paths, structured selectors target YAML frontmatter by default.
 Markdown address flags such as `--body`, `--section`, and `--task` switch
 `set` and `delete` to Dataview-style inline fields in the Markdown body.
+Task/list commands use `--section`, `--before`, and `--after` to address where
+task and list mutations happen; `--before` and `--after` match list items, not
+arbitrary prose.
 
 ## Transaction Model
 

docs/proposals/task-list-ops.md

@@ -1,5 +1,5 @@
 ---
-status: draft
+status: implemented
 depends_on:
   - markdown-addressing
 ---
@@ -64,8 +64,8 @@ etch task add memory/2026-04-29.md "Send follow-up" --section "## Action Items"
 - `list add` defaults to tail placement within the selected compatible list.
 - `--before` and `--after` use the placement rules from
   [Markdown Addressing](markdown-addressing.md) to choose an insertion point
-  relative to an existing item in the selected section or body. For `list add`
-  and `task add`, these anchors match list items, not arbitrary prose.
+  relative to an existing item in the selected section or body. For task/list
+  commands, these anchors match list items, not arbitrary prose.
 - `task add` is shorthand for `list add ... --task`.
 - `list add ... --task` constructs an unchecked task item.
 - If the selected section already contains a compatible list, Etch follows that
@@ -119,12 +119,12 @@ Docs:
 
 Code:
 
-- Add `task close`, `task open`, `list add`, and `task add` to the verb catalog
-  if approved.
+- Add `task close`, `task open`, `list add`, and `task add` to the verb
+  catalog.
 - Add fixtures for exact task matching, ambiguous task text, section scoping,
   nested tasks, list add marker inference, default tail placement, before/after
-  placement, task add shorthand, multiline add refusal, full-source add
-  refusal, optional Dataview completion metadata, and no-op behavior.
+  placement, task add shorthand, multiline add refusal, full-source add refusal,
+  custom task status refusal, and no-op behavior.
 
 ## Deferred Move Design
 
@@ -141,7 +141,7 @@ general block move. The hard part is not the spelling; it is preserving the
 source item's nested children, continuation lines, surrounding blank lines, and
 destination list structure without guessing.
 
-## Open Questions
+## Deferred
 
 - Should `task close` later set `[completion:: <date>]` in the same
   operation, or should that stay a separate Markdown field operation?

internal/etch/catalog.go

@@ -138,6 +138,8 @@ func commandPhrase(parts ...string) string {
 var markdownAddressFlags = []string{"--body", "--section", "--item", "--item-type", "--task", "--after", "--before", "--head", "--tail"}
 var markdownSetFlags = append(append([]string{"--json"}, markdownAddressFlags...), "--hidden")
 var markdownDeleteFlags = markdownAddressFlags
+var markdownTaskListFlags = []string{"--section", "--before", "--after"}
+var markdownListAddFlags = []string{"--section", "--before", "--after", "--task"}
 
 var allCommandSpecs = buildCommandSpecs()
 
@@ -155,6 +157,10 @@ func buildCommandSpecs() []commandSpec {
 		command("section replace", "section replace <path> <heading> <content>", "Replace the body under one Markdown heading.", ClassIdempotent, true, parseSection("replace")),
 		command("section append", "section append <path> <heading> <content>", "Append a block fragment under one Markdown heading.", ClassNonIdempotent, true, parseSection("append")),
 		command("section prepend", "section prepend <path> <heading> <content>", "Prepend a block fragment under one Markdown heading.", ClassNonIdempotent, true, parseSection("prepend")),
+		command("task close", "task close <path> <text> [--section <heading>] [--before <item>] [--after <item>]", "Ensure one Markdown task is closed.", ClassIdempotent, true, parseMarkdownTaskList("task close"), markdownTaskListFlags...),
+		command("task open", "task open <path> <text> [--section <heading>] [--before <item>] [--after <item>]", "Ensure one Markdown task is open, creating it when a destination is addressed.", ClassIdempotent, true, parseMarkdownTaskList("task open"), markdownTaskListFlags...),
+		command("list add", "list add <path> <text> [--section <heading>] [--task] [--before <item>] [--after <item>]", "Add one Markdown list item.", ClassNonIdempotent, true, parseMarkdownTaskList("list add"), markdownListAddFlags...),
+		command("task add", "task add <path> <text> [--section <heading>] [--before <item>] [--after <item>]", "Add one open Markdown task.", ClassNonIdempotent, true, parseMarkdownTaskList("task add"), markdownTaskListFlags...),
 		command("create", "create <path> [<content>]", "Create a new file; omitted content uses an extension-aware default.", ClassIdempotent, true, parseCreate),
 		command("move", "move <src> <dst>", "Move a file path.", ClassIdempotent, true, parseFileVerb("move")),
 		command("copy", "copy <src> <dst>", "Copy a file path.", ClassIdempotent, true, parseFileVerb("copy")),
@@ -445,6 +451,57 @@ func parseSection(action string) commandParser {
 	}
 }
 
+func parseMarkdownTaskList(verb string) commandParser {
+	return func(inv commandInvocation) ([]Operation, error) {
+		spec, op := inv.Spec, inv.Op
+		path, text, address, asTask, err := parseMarkdownTaskListArgs(inv.Args, verb == "list add")
+		if err != nil {
+			return nil, err
+		}
+		actualVerb := verb
+		if asTask {
+			actualVerb = "task add"
+		}
+		op.Verb, op.Kind, op.Class, op.Path, op.Value, op.ValueMode = actualVerb, "md-task-list", spec.Class, path, text, ValueModeString
+		op.Target = PlanTarget{Path: path, Part: "body", Section: address.Section}
+		op.Markdown = address
+		return parsedOperation(op)
+	}
+}
+
+func parseMarkdownTaskListArgs(args []string, allowTaskFlag bool) (path, text string, address markdownAddress, asTask bool, err error) {
+	var positional []string
+	for i := 0; i < len(args); i++ {
+		arg := args[i]
+		if arg == "--task" {
+			if !allowTaskFlag {
+				return "", "", markdownAddress{}, false, usagef("--task is only accepted by list add")
+			}
+			asTask = true
+			continue
+		}
+		parsed, next, err := parseMarkdownAddressFlag(args, i, &address, markdownTaskListAddressFlagOptions)
+		if err != nil {
+			return "", "", markdownAddress{}, false, err
+		}
+		if parsed {
+			i = next
+			continue
+		}
+		if strings.HasPrefix(arg, "--") {
+			return "", "", markdownAddress{}, false, usagef("unknown Markdown task/list flag %s", arg)
+		}
+		positional = append(positional, arg)
+	}
+	if len(positional) != 2 {
+		return "", "", markdownAddress{}, false, usagef("usage: etch <task/list command> <path> <text> [flags]")
+	}
+	if _, err := markdownPlacementFromFlags(false, false, address.Before, address.After); err != nil {
+		return "", "", markdownAddress{}, false, err
+	}
+	return positional[0], positional[1], address, asTask, nil
+}
+
 func parseTable(format string, tablePath ...string) commandParser {
 	return func(inv commandInvocation) ([]Operation, error) {
 		op, args := inv.Op, inv.Args
@@ -830,10 +887,10 @@ func fillDescriptor(op *Operation) {
 	} else if op.Target.Selector != "" {
 		parts = append(parts, op.Target.Selector)
 	}
-	if op.Target.Section != "" && op.Kind != "md-field" {
+	if op.Target.Section != "" && op.Kind != "md-field" && op.Kind != "md-task-list" {
 		parts = append(parts, shellQuote(op.Target.Section))
 	}
-	if op.Kind == "md-field" {
+	if op.Kind == "md-field" || op.Kind == "md-task-list" {
 		parts = appendMarkdownAddressDescriptor(parts, op.Markdown)
 	}
 	if op.Target.Range != "" {
@@ -971,9 +1028,9 @@ func printHelp(w io.Writer, topic string, all bool) error {
 		}
 		fmt.Fprintln(w)
 		if all {
-			fmt.Fprint(w, "Topics: model, scripts, selectors, values, fields, plans, security, conflicts, addressing, section, table, csv\n")
+			fmt.Fprint(w, "Topics: model, scripts, selectors, values, fields, plans, security, conflicts, addressing, section, tasks, table, csv\n")
 		} else {
-			fmt.Fprint(w, "Topics: model, scripts, selectors, values, fields, plans, security, conflicts, addressing, section, table, csv. Use --all for plumbing commands.\n")
+			fmt.Fprint(w, "Topics: model, scripts, selectors, values, fields, plans, security, conflicts, addressing, section, tasks, table, csv. Use --all for plumbing commands.\n")
 		}
 	case "scripts":
 		fmt.Fprint(w, scriptsHelp)
@@ -995,6 +1052,8 @@ func printHelp(w io.Writer, topic string, all bool) error {
 		fmt.Fprint(w, modelHelp)
 	case "section":
 		fmt.Fprint(w, sectionHelp)
+	case "tasks":
+		fmt.Fprint(w, tasksHelp)
 	case "table", "csv":
 		fmt.Fprint(w, tableHelp)
 	default:
@@ -1096,6 +1155,22 @@ Repeated matching headings are ambiguous. Append/prepend trim payload boundary b
 and use one blank line between non-empty block fragments.
 `
 
+const tasksHelp = `Markdown task/list commands operate on exact source-normalized item text.
+
+Commands:
+  etch task close note.md "Send follow-up" --section Actions
+  etch task open note.md "Send follow-up" --section Actions
+  etch list add note.md "Launch notes" --section Actions
+  etch task add note.md "Send follow-up" --section Actions
+
+task close changes [ ] to [x] and never creates missing tasks.
+task open ensures an open task: it reopens [x]/[X], no-ops on [ ], and creates
+missing tasks only when a destination address such as --section, --before, or
+--after is supplied. Custom checkbox statuses fail.
+--before and --after match list items, not arbitrary prose.
+list add and task add create source from plain item text; do not include "- " or "- [ ]".
+`
+
 const tableHelp = `Tables are ordered rows and named columns of string cells.
 
 CSV:

internal/etch/formats_test.go

@@ -722,6 +722,35 @@ func TestMarkdownInlineFieldCommandsCommitAndMaterialize(t *testing.T) {
 	}
 }
 
+func TestMarkdownTaskListCommandsCommitAndMaterialize(t *testing.T) {
+	dir := initRepo(t)
+	writeFile(t, dir, "note.md", "# Note\n\n## Actions\n- [ ] Send follow-up\n")
+	commitAll(t, dir, "initial")
+
+	runOK(t, dir, "task", "close", "note.md", "Send follow-up", "--section", "Actions")
+	got := testGit(t, dir, "show", "HEAD:note.md")
+	if got != "# Note\n\n## Actions\n- [x] Send follow-up\n" {
+		t.Fatalf("task close output = %q", got)
+	}
+	subject := stringsTrim(testGit(t, dir, "log", "-1", "--format=%s"))
+	if subject != `etch task close note.md --section Actions "Send follow-up"` {
+		t.Fatalf("task close subject = %q", subject)
+	}
+
+	runOK(t, dir, "task", "open", "note.md", "Review draft", "--section", "Actions")
+	got = testGit(t, dir, "show", "HEAD:note.md")
+	if got != "# Note\n\n## Actions\n- [x] Send follow-up\n- [ ] Review draft\n" {
+		t.Fatalf("task open create output = %q", got)
+	}
+	wt, err := os.ReadFile(filepath.Join(dir, "note.md"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if string(wt) != got {
+		t.Fatalf("worktree not materialized:\nwt=%s\nhead=%s", wt, got)
+	}
+}
+
 func TestEvalMarkdownSectionReplace(t *testing.T) {
 	tests := []struct {
 		name    string

internal/etch/help_test.go

@@ -7,7 +7,7 @@ import (
 )
 
 func TestHelpTopicsSnapshotSmoke(t *testing.T) {
-	for _, topic := range []string{"", "model", "scripts", "selectors", "values", "fields", "plans", "security", "conflicts", "addressing", "section", "table", "csv"} {
+	for _, topic := range []string{"", "model", "scripts", "selectors", "values", "fields", "plans", "security", "conflicts", "addressing", "section", "tasks", "table", "csv"} {
 		var out bytes.Buffer
 		if err := printHelp(&out, topic, false); err != nil {
 			t.Fatalf("help %q: %v", topic, err)
@@ -29,7 +29,7 @@ func TestDefaultHelpTableExcludesPlumbing(t *testing.T) {
 			t.Fatalf("default help contains plumbing command %q:\n%s", hidden, text)
 		}
 	}
-	for _, shown := range []string{"set <path>", "table set", "section replace", "section append", "section prepend"} {
+	for _, shown := range []string{"set <path>", "table set", "section replace", "section append", "section prepend", "task close", "list add"} {
 		if !strings.Contains(text, shown) {
 			t.Fatalf("default help missing porcelain command %q:\n%s", shown, text)
 		}

internal/etch/markdown_address_decode.go

@@ -0,0 +1,106 @@
+package etch
+
+type markdownAddressFlagOptions struct {
+	Body     bool
+	Section  bool
+	Item     bool
+	ItemType bool
+	Task     bool
+	After    bool
+	Before   bool
+	Head     bool
+	Tail     bool
+	Hidden   bool
+}
+
+var markdownFieldAddressFlagOptions = markdownAddressFlagOptions{
+	Body: true, Section: true, Item: true, ItemType: true, Task: true,
+	After: true, Before: true, Head: true, Tail: true,
+}
+
+var markdownTaskListAddressFlagOptions = markdownAddressFlagOptions{
+	Section: true, After: true, Before: true,
+}
+
+func isMarkdownAddressFlag(arg string) bool {
+	switch arg {
+	case "--body", "--section", "--item", "--item-type", "--task", "--after", "--before", "--head", "--tail", "--hidden":
+		return true
+	default:
+		return false
+	}
+}
+
+func parseMarkdownAddressFlag(args []string, index int, address *markdownAddress, options markdownAddressFlagOptions) (bool, int, error) {
+	arg := args[index]
+	switch arg {
+	case "--body":
+		if !options.Body {
+			return false, index, nil
+		}
+		address.Body = true
+		return true, index, nil
+	case "--section", "--item", "--item-type", "--task", "--after", "--before":
+		if !markdownAddressFlagWithValueAllowed(arg, options) {
+			return false, index, nil
+		}
+		if index+1 >= len(args) {
+			return true, index, usagef("%s requires a value", arg)
+		}
+		value := args[index+1]
+		switch arg {
+		case "--section":
+			address.Section = value
+		case "--item":
+			address.Item = value
+		case "--item-type":
+			address.ItemTypes = append(address.ItemTypes, value)
+		case "--task":
+			address.Task = value
+		case "--after":
+			address.After = value
+		case "--before":
+			address.Before = value
+		}
+		return true, index + 1, nil
+	case "--head":
+		if !options.Head {
+			return false, index, nil
+		}
+		address.Head = true
+		return true, index, nil
+	case "--tail":
+		if !options.Tail {
+			return false, index, nil
+		}
+		address.Tail = true
+		return true, index, nil
+	case "--hidden":
+		if !options.Hidden {
+			return false, index, nil
+		}
+		address.Hidden = true
+		return true, index, nil
+	default:
+		return false, index, nil
+	}
+}
+
+func markdownAddressFlagWithValueAllowed(arg string, options markdownAddressFlagOptions) bool {
+	switch arg {
+	case "--section":
+		return options.Section
+	case "--item":
+		return options.Item
+	case "--item-type":
+		return options.ItemType
+	case "--task":
+		return options.Task
+	case "--after":
+		return options.After
+	case "--before":
+		return options.Before
+	default:
+		return false
+	}
+}