README.md

@@ -21,7 +21,10 @@ Within files, `@`-prefixed markers at the beginning of paragraphs or headings de
 ## Commands
 
 - `streamd` / `streamd new` — Create a new timestamped markdown entry, opening your editor
-- `streamd todo` — Show all open tasks (shards with `@Task` markers)
+- `streamd todo` — Show all open tasks (shards with `@Task` markers), numbered for easy reference
+- `streamd todo N edit` — Edit task N in your editor, jumping to the task's line
+- `streamd todo N done` — Mark task N as done by inserting `@Done` after `@Task`
+- `streamd todo --show-future` — Include tasks with future dates in the listing
 - `streamd edit [number]` — Edit a stream file by index (most recent first)
 - `streamd timesheet` — Generate time reports from `@Timesheet` markers
 
@@ -60,4 +63,8 @@ The timesheet command will calculate expected vs actual working hours based on t
 
 Running `streamd` opens your editor to create a new entry. After saving, the file is renamed based on its timestamp and any markers found in the content.
 
-Running `streamd todo` finds all shards marked as open tasks and displays them as rich-formatted panels in your terminal.
+Running `streamd todo` finds all shards marked as open tasks and displays them numbered in your terminal. Tasks with future dates are hidden by default (use `--show-future` to include them). Tasks are sorted by date with oldest first (task 1 is the oldest).
+
+You can quickly edit or complete tasks by number:
+- `streamd todo 1 edit` opens task 1 in your editor at the correct line
+- `streamd todo 1 done` marks task 1 as done by inserting `@Done` after `@Task`

REQUIREMENTS.md

@@ -387,11 +387,40 @@ Provide recursive search through the shard tree:
 | Command | Description |
 |---------|-------------|
 | `streamd new` | Create new timestamped file, open editor, rename with markers on close |
-| `streamd todo` | List all shards with `task: "open"` |
+| `streamd todo` | List all shards with `task: "open"`, numbered, hiding future tasks |
+| `streamd todo --show-future` | Include tasks with future dates in the todo listing |
+| `streamd todo N edit` | Edit task N in editor, cursor positioned at task line |
+| `streamd todo N done` | Mark task N as done by inserting `@Done` after `@Task` |
 | `streamd edit [n]` | Edit nth file (supports negative indexing for recent files) |
 | `streamd timesheet` | Generate formatted timesheet report with expected/actual hours |
 | `streamd completions <shell>` | Generate shell completions (bash, zsh, fish, elvish, powershell) |
 
+### R21: Todo Command Behavior
+
+**Task Numbering:**
+- Tasks are numbered starting from 1 (oldest task = 1)
+- Tasks are sorted by their `moment` field in ascending order
+- Output format: `[N] --- file.md:line ---` followed by task content
+
+**Future Task Filtering:**
+- By default, tasks with `moment > now` are hidden from the listing
+- The `--show-future` flag includes all tasks regardless of their moment
+- When using `todo N edit` or `todo N done`, all tasks (including future) are considered for number lookup
+
+**Edit Action (`todo N edit`):**
+- Opens the task's file in `$EDITOR` (defaults to `vi`)
+- Uses `+LINE` argument to position cursor at task's start line
+- Errors if N is 0 or exceeds the task count
+
+**Done Action (`todo N done`):**
+- Reads the file and modifies the line at task's start_line
+- Inserts ` @Done` immediately after `@Task`
+- Preserves trailing newline if the original file had one
+- Errors if:
+  - N is 0 or exceeds the task count
+  - Multiple `@Task` markers found on the same line
+  - No `@Task` marker found on the expected line
+
 ---
 
 ## Application Configuration