diff --git a/AGENTS.md b/AGENTS.md
index 481d82f..a412f1c 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1,118 +1,41 @@
-# CLAUDE.md
-
-This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+# Lorah
 
 ## Project Overview
 
-Lorah is a simple infinite-loop harness for long-running autonomous coding agents. It runs Claude Code CLI in a continuous loop, parsing stream-JSON output and formatting it nicely. The agent manages its own workflow - Lorah just provides the loop, error recovery, and output formatting. Follows the [Ralph pattern](https://ghuntley.com/ralph/). Distributed as a single self-contained binary with no external runtime dependencies.
+Lorah is a simple infinite-loop harness for long-running autonomous coding agents. It runs Claude Code CLI in a continuous loop, parsing stream-JSON output and formatting it nicely. Includes a task management system for structured agent workflow coordination. The agent manages its own workflow — Lorah just provides the loop, error recovery, output formatting, and task tracking. Follows the Ralph pattern. Distributed as a single self-contained binary with no external runtime dependencies.
 
 ## Commands
 
 ```bash
-# Build binary
-go build -o ./bin/lorah .
-
-# Install globally
-go install .
-
-# Run Lorah
-lorah PROMPT.md [claude-flags...]
+make build                         # Build binary
+go run . run PROMPT.md             # Development run
+lorah run PROMPT.md [flags...]     # Run loop (all flags after prompt passed to claude CLI)
+lorah task <subcommand> [args...]  # Task management
 ```
 
-All arguments after `PROMPT.md` are passed directly to Claude CLI:
-
-```bash
-# With settings file
-lorah PROMPT.md --settings .lorah/settings.json
-
-# With specific model
-lorah PROMPT.md --model claude-opus-4-6
-
-# With multiple flags
-lorah PROMPT.md --settings settings.json --max-turns 50 --verbose
-```
-
-For development:
-
-```bash
-go run . PROMPT.md [claude-flags...]
-```
-
-No tests currently - the implementation is simple enough to verify manually. No linter or formatter beyond `gofmt`.
+Use TDD — write tests before implementation. Use `make fmt` and `make lint`.
 
 ## Architecture
 
-Lorah is a single-file Go program that implements a simple infinite loop:
-
 ```
-1. Execute: claude -p --output-format=stream-json --verbose [user-flags...] PROMPT.md
-2. Parse stream-JSON line-by-line from stdout
-3. Format output with color-coded sections and tool activity
-4. On error: print error, sleep 5s, retry
-5. On success: continue immediately to next iteration
-6. Repeat forever until Ctrl+C
+main.go                   CLI router: subcommand dispatch, help text, version
+internal/loop/
+  loop.go                 Run() entry point, signal handling, infinite loop
+  claude.go               Subprocess execution
+  output.go               Stream-JSON parsing and formatted output
+  constants.go            ANSI colors, buffer size, retry delay
+internal/task/
+  task.go                 Core types: Phase, Section, Task, TaskStatus, TaskList, Filter
+  storage.go              Storage interface
+  json_storage.go         JSONStorage implementation (tasks.json)
+  format.go               Output formatters: json, markdown
+  cmd.go                  CLI subcommand handlers
+docs/design/              Design specifications (authoritative reference)
 ```
 
-### File Structure
-
-```
-main.go              Single file containing everything
-  - Constants        ANSI color codes, retry delay
-  - Message Types    stream-JSON message/content block structs
-  - Main Loop        Infinite execution loop with signal handling
-  - Claude Exec      Build command, pipe I/O, run subprocess
-  - Message Parsing  Parse newline-delimited JSON into typed structs
-  - Output Format    Color-coded section headers, tool activity display
-go.mod               Go module definition
-go.sum               Dependency checksums (none - stdlib only)
-```
-
-### Main Sections
-
-**Constants** — ANSI color codes for terminal output and retry delay configuration.
-
-**Helper Functions** — `printSection()` outputs labeled sections with color formatting.
-
-**Main Loop** — Entry point:
-
-- Parses CLI args: `PROMPT.md` and optional Claude CLI flags
-- Handles `--version` and `--help` flags
-- Sets up signal handler for graceful Ctrl+C shutdown
-- Runs infinite loop calling `runClaude()` with error recovery
-
-**Claude Execution** — `runClaude()` function:
-
-- Opens prompt file and pipes it to stdin
-- Builds `claude` command with `-p`, `--output-format=stream-json`, `--verbose`, and user flags
-- Streams stdout to `printMessages()` for real-time output
-- Returns error if command fails
-
-**Output Formatting** — `printMessages()` function:
-
-- Scans stdout line-by-line (newline-delimited JSON)
-- Parses each line as `map[string]any` for flexibility
-- Gracefully skips malformed/unknown message types for forward compatibility
-- Displays color-coded section headers: `==> Claude`, `==> Lorah`, `==> Error`
-- Shows tool activity: `==> Bash`, `==> Read`, etc. with relevant input displayed
-- Extracts relevant input params (command, file_path, pattern, url, etc.) based on tool name
-- Truncates long tool inputs to 3 lines for readability
-
-## Key Patterns
-
-- **Single file** — Entire program in one `main.go` file. No packages, no navigation overhead. Readable in one sitting.
-- **No configuration** — Zero config files. Prompts are plain markdown. Claude CLI flags passed through directly.
-- **Ralph pattern** — Simple infinite loop. Agent decides workflow. Harness provides loop + nice output. Inspired by [Geoffrey Huntley's Ralph](https://ghuntley.com/ralph/).
-- **Agent-driven** — No phase orchestration. Agent reads codebase, decides what to do next, makes progress iteratively.
-- **Filesystem as state** — No session files. Git commits show progress. Agent reads files to understand context.
-- **Flag passthrough** — All args after `PROMPT.md` passed directly to `claude` CLI. User has full control.
-- **CLI-native security** — Security enforced through Claude CLI `--settings` flag (sandbox, permissions). See [Claude Code Settings](https://code.claude.com/docs/en/settings).
-- **Stream processing** — stdout parsed line-by-line as newline-delimited JSON; unknown types skipped gracefully for forward compatibility.
-- **Simple error handling** — Fixed 5-second retry delay on errors. No exponential backoff complexity.
-- **Color-coded output** — Section headers and tool activity formatted with ANSI colors for readability.
-
 ## Design Principles
 
-**Ralph Philosophy**: The agent is smart enough to manage its own workflow. Don't orchestrate - provide a simple loop and trust the model.
+**Ralph Philosophy**: The agent is smart enough to manage its own workflow. Don't orchestrate — provide a simple loop and trust the model.
 
 **Radical Simplicity**: Every line of code is overhead. The simplest solution that works is the best solution. Prefer deleting code over adding it.
 
@@ -120,13 +43,10 @@ go.sum               Dependency checksums (none - stdlib only)
 
 **No Ceremony**: No config files, session state, lock files, or scaffolding commands. Just a prompt file and a loop.
 
-Required reading:
+**Filesystem as State**: No session files. Git commits show progress. Agent reads files to understand context.
 
-- [Ralph by Geoffrey Huntley](https://ghuntley.com/ralph/) - The pattern this implementation follows
-- [Building Effective Agents](https://www.anthropic.com/research/building-effective-agents) - Agent design principles from Anthropic
-- [Agent SDK Overview](https://platform.claude.com/docs/en/agent-sdk/overview) - Understanding agent capabilities
-- [Claude Code Sandboxing](https://www.anthropic.com/engineering/claude-code-sandboxing) - Security model
+**Design Specifications**: Authoritative design docs live in `docs/design/`. When in doubt about intended behavior, consult the specs: `cli.md`, `run.md`, `output.md`, `task.md`.
 
 ## Dependencies
 
-No external runtime dependencies. All functionality uses the Go standard library. The `claude` CLI (separate install) is the only runtime requirement for executing agent sessions.
+No external runtime dependencies. All functionality uses the Go standard library. The `claude` CLI (separate install) is the only runtime requirement.
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 3c72a4e..30ea1c9 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -7,6 +7,25 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- Subcommand-based CLI: `lorah <command> [arguments]` with `run` and `task` commands
+- Task management system (`lorah task`) with 6 subcommands: list, get, create, update, delete, export
+- JSON-based task storage in `tasks.json` with Storage interface for future backend swaps
+- Two task output formats: json, markdown (default); `--flat` flag on `list` for flat bullet output
+- Loop status messages now include iteration number
+
+### Changed
+
+- **BREAKING**: CLI changed to `lorah run <prompt-file> [claude-flags...]` (was `lorah <prompt-file> [claude-flags...]`)
+- Removed color from Claude text and thinking output sections
+
+### Fixed
+
+- Removed extra newline before loop error output
+- Tool name matching now uses prefix match for Task tool names
+- Scanner errors are now handled gracefully instead of being silently ignored
+
 ## [0.4.0] - 2026-03-09
 
 ### Changed
@@ -25,7 +44,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Added
 
 - Infinite loop execution following [Ralph pattern](https://ghuntley.com/ralph/)
-- Direct flag passthrough to Claude CLI
+- Direct flag passthrough to Claude Code CLI
 
 ### Changed
 
@@ -42,7 +61,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Changed
 
-- **BREAKING**: Configuration format changed to a split structure with `harness` (lorah settings) and `claude` (passthrough to Claude CLI) sections. Existing configs require migration—run `lorah info template` to see the new format.
+- **BREAKING**: Configuration format changed to a split structure with `harness` (lorah settings) and `claude` (passthrough to Claude Code CLI) sections. Existing configs require migration—run `lorah info template` to see the new format.
 - Updated documentation to document two-phase execution model with fixed file names (initialization and implementation phases)
 - Renamed `docs/setup-guide.md` to `docs/getting-started.md`
 - Renamed review workflow prompts from `inventory.md`/`fix.md` to `initialization.md`/`implementation.md`
diff --git a/Makefile b/Makefile
index 02c37ec..9bcdb58 100644
--- a/Makefile
+++ b/Makefile
@@ -1,4 +1,4 @@
-.PHONY: help build clean fmt lint install
+.PHONY: help build clean fmt lint test
 
 # Default target - show help
 help:
@@ -9,10 +9,10 @@ help:
 	@echo "Targets:"
 	@echo "  help           Show this help message"
 	@echo "  build          Build the lorah binary"
-	@echo "  install        Install lorah to GOPATH/bin"
 	@echo "  clean          Remove build artifacts"
 	@echo "  fmt            Format all Go code"
 	@echo "  lint           Run go vet for static analysis"
+	@echo "  test           Run all tests"
 
 # Build the lorah binary
 build:
@@ -21,12 +21,6 @@ build:
 	echo "Building lorah $$VERSION..."; \
 	go build -ldflags "-X 'main.Version=$$VERSION'" -o ./bin/lorah .
 
-# Install lorah to GOPATH/bin
-install:
-	@VERSION=$$(date -u '+dev+%Y%m%d%H%M%S'); \
-	echo "Installing lorah $$VERSION..."; \
-	go install -ldflags "-X 'main.Version=$$VERSION'" .
-
 # Clean build artifacts
 clean:
 	rm -rf ./bin
@@ -45,3 +39,7 @@ fmt:
 lint:
 	@echo "Running go vet..."
 	go vet ./...
+
+# Run all tests
+test:
+	go test ./...
diff --git a/README.md b/README.md
index 44ee07c..ff6a9e9 100644
--- a/README.md
+++ b/README.md
@@ -22,20 +22,22 @@ But you get raw `stream-json` output that's unreadable:
 **Lorah gives you clean, color-coded output:**
 
 ```
-==> Claude
+⏺ Claude
 Let me read the file
-==> Read
+
+⏺ Read
 /path/to/file
 ```
 
-Plus automatic error recovery, graceful shutdown, and full Claude CLI compatibility.
+Plus automatic error recovery, graceful shutdown, and full Claude Code CLI compatibility.
 
 **Key Features:**
 
 - **Formatted output** - Color-coded sections and tool activity (the main reason Lorah exists)
 - **Simple infinite loop** - Runs continuously until you stop it
 - **Automatic error recovery** - Retries on failures with 5-second delay
-- **Flag passthrough** - All Claude CLI flags work transparently
+- **Flag passthrough** - All Claude Code CLI flags work transparently
+- **Task management** - Structured task tracking for agent workflow coordination
 
 ## Prerequisites
 
@@ -49,22 +51,33 @@ brew install cpplain/tap/lorah
 
 ## Usage
 
-Lorah is an implementatioin of the Ralph loop. You must understand the Ralph technique to use Lorah effectively.
+Lorah is an implementation of the Ralph loop. You must understand the Ralph technique to use Lorah effectively.
 
 Learn more about the Ralph technique: [Ralph Wiggum as a "software engineer"](https://ghuntley.com/ralph/) by Geoffrey Huntley
 
 **Syntax:**
 
 ```bash
-lorah <prompt-file> [claude-flags...]
+lorah <command> [arguments]
+```
+
+**Run loop:**
+
+```bash
+lorah run PROMPT.md
+lorah run PROMPT.md --settings .lorah/settings.json
+lorah run PROMPT.md --model claude-opus-4-6 --max-turns 50
 ```
 
-**Examples:**
+**Task management:**
 
 ```bash
-lorah PROMPT.md
-lorah PROMPT.md --settings .lorah/settings.json
-lorah PROMPT.md --model claude-opus-4-6 --max-turns 50
+lorah task list --status=pending
+lorah task get <id>
+lorah task create --subject="Fix auth bug"
+lorah task update <id> --status=completed
+lorah task delete <id>
+lorah task export
 ```
 
 ## License
diff --git a/docs/design/README.md b/docs/design/README.md
new file mode 100644
index 0000000..a3d790f
--- /dev/null
+++ b/docs/design/README.md
@@ -0,0 +1,30 @@
+# Lorah Specifications
+
+Design documentation for `lorah`, a simple infinite-loop harness for Claude Code.
+
+## Index
+
+| Spec                   | Description                                                                    |
+| ---------------------- | ------------------------------------------------------------------------------ |
+| [cli.md](cli.md)       | Command-line interface: subcommands, routing, flags, help, version, exit codes |
+| [run.md](run.md)       | `run` command: loop lifecycle, signal handling, retry, subprocess execution    |
+| [output.md](output.md) | Output system: stream-JSON parsing, color-coded formatting, tool display       |
+| [task.md](task.md)     | `task` command: CRUD subcommands, JSON storage, agent integration              |
+
+## Glossary
+
+| Term               | Definition                                                                                 |
+| ------------------ | ------------------------------------------------------------------------------------------ |
+| **prompt file**    | A markdown file containing instructions for the Claude Code agent, piped to `claude` stdin |
+| **loop iteration** | One complete execution of the Claude Code CLI subprocess from start to finish              |
+| **stream-JSON**    | Newline-delimited JSON output by Claude Code CLI's `--output-format=stream-json` flag      |
+| **claude flags**   | Arguments passed through to the `claude` CLI unchanged after the prompt file               |
+| **task file**      | JSON file (`tasks.json`) storing structured task data for agent workflow management        |
+
+## Design Principles
+
+- **Ralph Philosophy**: the agent is smart enough to manage its own workflow; the harness provides the loop and nice output, nothing more
+- **Radical Simplicity**: the simplest solution that works is the best solution; prefer deleting code over adding it
+- **Agent in Control**: the harness provides the loop and output; the agent reads the codebase, decides what to do, and makes progress
+- **No Ceremony**: no config files, session state, lock files, or scaffolding commands
+- **No External Dependencies**: stdlib only; `claude` CLI is the only runtime requirement
diff --git a/docs/design/cli.md b/docs/design/cli.md
new file mode 100644
index 0000000..3771daf
--- /dev/null
+++ b/docs/design/cli.md
@@ -0,0 +1,230 @@
+# CLI Specification
+
+---
+
+## 1. Overview
+
+### Purpose
+
+`lorah` uses a subcommand-based CLI. The first argument selects the operation.
+All routing is a stdlib `switch` statement with no external dependencies.
+`main.go` contains only routing logic — no business logic lives there.
+
+### Goals
+
+- **Subcommand-based**: `lorah <command> [args...]` with unambiguous routing
+- **Thin router**: `main.go` is ~60 lines of routing only
+- **Flag passthrough**: `run` passes all trailing args to `claude` CLI unchanged
+- **Helpful on error**: unknown commands print error + usage; missing args explain correct usage
+
+### Non-Goals
+
+- External flag parsing library (no cobra, no pflag)
+- Shell completion
+- Typo suggestion for unknown commands
+
+---
+
+## 2. Interface
+
+### Usage
+
+```
+lorah <command> [arguments]
+```
+
+### Commands
+
+| Command | Arguments                         | Description                             |
+| ------- | --------------------------------- | --------------------------------------- |
+| `run`   | `<prompt-file> [claude-flags...]` | Run Claude Code CLI in an infinite loop |
+| `task`  | `<subcommand> [args...]`          | Manage tasks                            |
+
+### Top-Level Flags
+
+| Flag        | Short            | Description                     |
+| ----------- | ---------------- | ------------------------------- |
+| `--version` | `-V`, `-version` | Print version and exit 0        |
+| `--help`    | `-h`, `-help`    | Show top-level usage and exit 0 |
+
+Top-level flags are only recognized as `os.Args[1]`. They are not parsed anywhere else.
+
+---
+
+## 3. Behavior
+
+### Routing Rules
+
+1. No arguments → print top-level usage, exit 1
+2. `--version`, `-version`, `-V` → print `lorah <version>`, exit 0
+3. `--help`, `-help`, `-h` → print top-level usage, exit 0
+4. `run` → dispatch to `runCmd` with `os.Args[2:]`
+5. `task` → dispatch to `taskCmd` with `os.Args[2:]`
+6. Anything else → print `Unknown command: <input>` + top-level usage to stderr, exit 1
+
+### Version Output
+
+```
+lorah <version>
+```
+
+`Version` is `"dev"` by default; injected at build time via `-ldflags '-X main.Version=...'`.
+
+### Top-Level Usage (`lorah` or `lorah --help`)
+
+```
+Usage: lorah <command> [arguments]
+
+Simple infinite-loop harness for Claude Code.
+
+Commands:
+  run     Run Claude Code CLI in an infinite loop
+  task    Manage tasks
+
+Flags:
+  -V, --version    Print version and exit
+  -h, --help       Show this help message
+
+Run 'lorah <command> --help' for command-specific help.
+```
+
+### Run Command Usage (`lorah run --help`)
+
+```
+Usage: lorah run <prompt-file> [claude-flags...]
+
+Run Claude Code CLI in a continuous loop with formatted output.
+Retries automatically on error with a 5-second delay.
+
+Arguments:
+  <prompt-file>      Path to prompt file (required)
+  [claude-flags...]  Flags passed directly to claude CLI
+
+Examples:
+  lorah run prompt.md
+  lorah run task.txt --settings .lorah/settings.json
+  lorah run instructions.md --model claude-opus-4-6 --max-turns 50
+
+Flags:
+  -h, --help    Show this help message
+```
+
+### Task Command Usage (`lorah task --help`)
+
+```
+Usage: lorah task <subcommand> [args...] [flags...]
+
+Manage tasks stored in tasks.json.
+
+Subcommands:
+  list        List tasks
+  get         Get task details
+  create      Create a new task
+  update      Update a task
+  delete      Delete a task
+  export      Export tasks to markdown
+
+Flags:
+  -h, --help    Show this help message
+
+Run 'lorah task <subcommand> --help' for subcommand-specific help.
+```
+
+---
+
+## 4. Router Implementation
+
+### `main.go` Structure
+
+```go
+var Version = "dev"
+
+func main()          // subcommand switch on os.Args[1]
+func runCmd(args []string)   // extract prompt file + claude flags, call loop.Run()
+func taskCmd(args []string)  // dispatch to task subcommand handler
+func printUsage()            // top-level help text
+func printRunUsage()         // run-specific help text
+func printTaskUsage()        // task-specific help text
+```
+
+### What Lives in `main.go`
+
+- `var Version` — ldflags target must be in package `main`
+- `main()` — the subcommand switch only
+- `runCmd()`, `taskCmd()` — argument validation and dispatch
+- `printUsage()`, `printRunUsage()`, `printTaskUsage()` — help text
+
+Nothing else. No signal handling, no loop logic, no output formatting, no task logic.
+
+### Flag Parsing
+
+Top-level routing uses a stdlib `switch` on `os.Args[1]`. Subcommand flag parsing
+(e.g., `--status=pending`, `--format=markdown`) uses `flag.NewFlagSet` — also stdlib.
+No external flag parsing library is used anywhere in the codebase.
+
+### `runCmd` Behavior
+
+```go
+func runCmd(args []string)
+```
+
+1. If `len(args) == 0` → print run usage, exit 1
+2. If `args[0]` is `--help`, `-help`, or `-h` → print run usage, exit 0
+3. `promptFile = args[0]`, `claudeFlags = args[1:]`
+4. Call `loop.Run(promptFile, claudeFlags)`
+
+### `taskCmd` Behavior
+
+```go
+func taskCmd(args []string)
+```
+
+1. If `len(args) == 0` → print task usage, exit 1
+2. If `args[0]` is `--help`, `-help`, or `-h` → print task usage, exit 0
+3. Dispatch on `args[0]` (subcommand name) to the appropriate handler in `internal/task`
+4. Unknown subcommand → print `Unknown subcommand: <input>` + task usage to stderr, exit 1
+
+---
+
+## 5. Exit Codes
+
+| Code | Meaning                                   |
+| ---- | ----------------------------------------- |
+| 0    | Success (including `--version`, `--help`) |
+| 1    | Runtime error or usage error              |
+
+---
+
+## 6. Examples
+
+```sh
+# Version and help
+lorah --version
+lorah --help
+
+# Run command
+lorah run prompt.md
+lorah run prompt.md --settings .lorah/settings.json
+lorah run prompt.md --model claude-opus-4-6 --max-turns 50
+lorah run --help
+
+# Task command
+lorah task list
+lorah task list --status=pending
+lorah task get 1
+lorah task update 1 --status=completed --notes="Done"
+lorah task --help
+
+# Error cases
+lorah unknown              # Unknown command: unknown
+lorah run                  # shows run usage, exits 1
+lorah task                 # shows task usage, exits 1
+```
+
+---
+
+## 7. Related Specifications
+
+- [run.md](run.md) — `run` command behavior and loop lifecycle
+- [task.md](task.md) — `task` subcommand behavior and storage
+- [output.md](output.md) — output formatting used by `run`
diff --git a/docs/design/output.md b/docs/design/output.md
new file mode 100644
index 0000000..5d9c60b
--- /dev/null
+++ b/docs/design/output.md
@@ -0,0 +1,196 @@
+# Output Specification
+
+---
+
+## 1. Overview
+
+### Purpose
+
+The output system parses Claude Code CLI's stream-JSON stdout and displays color-coded,
+human-readable sections in real-time as each line arrives.
+
+### Goals
+
+- **Real-time**: output displayed as stream-JSON lines arrive, not buffered to end
+- **Color-coded**: section headers colored by source for visual scanning
+- **Forward-compatible**: unknown message types and block types silently skipped
+- **Truncated**: multi-line tool inputs condensed to first line plus remaining count
+
+### Non-Goals
+
+- Machine-readable (JSON) output from Lorah itself
+- Log files or output persistence
+- Configurable color themes or color disabling
+
+---
+
+## 2. Color Scheme
+
+| Constant     | ANSI Code  | Use                  |
+| ------------ | ---------- | -------------------- |
+| `colorReset` | `\033[0m`  | Reset all formatting |
+| `colorGreen` | `\033[32m` | Tool section icon    |
+| `colorBlue`  | `\033[34m` | Lorah section icon   |
+| `colorBold`  | `\033[1m`  | Section label text   |
+| `colorRed`   | `\033[31m` | Error section icon   |
+
+---
+
+## 3. Section Format
+
+### Signature
+
+```go
+func printSection(label, color, content string)
+```
+
+### Output Template
+
+```
+<color>⏺<reset> <bold><label><reset>
+<content trimmed>
+
+```
+
+- The icon (`⏺`) is colored; the label is bold; both are reset after
+- If `content` is empty, only the icon+label line and blank line are printed
+- Content is trimmed of leading and trailing whitespace before printing
+
+---
+
+## 4. Stream-JSON Parsing
+
+### Signature
+
+```go
+func printMessages(r io.Reader)
+```
+
+### Scanner Configuration
+
+- `bufio.Scanner` reading from `r` line-by-line
+- Buffer initialized to 4096 bytes, max `maxBufferSize` (1MB)
+- Empty lines are skipped
+- Lines that fail JSON unmarshal are silently skipped (forward compatibility)
+
+### Top-Level Message Types
+
+| `msg["type"]`   | Handling                                                     |
+| --------------- | ------------------------------------------------------------ |
+| `"assistant"`   | Parse `msg["message"]["content"]` as array of content blocks |
+| `"result"`      | Display only if `msg["is_error"]` is `true`                  |
+| (anything else) | Silently skipped                                             |
+
+### Content Block Types (within `assistant` messages)
+
+| `block["type"]` | Display                                                    |
+| --------------- | ---------------------------------------------------------- |
+| `"text"`        | `printSection("Claude", "", block["text"])`                |
+| `"thinking"`    | `printSection("Claude (thinking)", "", block["thinking"])` |
+| `"tool_use"`    | Tool display (see section 5)                               |
+| (anything else) | Silently skipped                                           |
+
+### Result Messages
+
+Only error results are displayed:
+
+```
+msg["is_error"] == true  →  printSection("Result (error)", colorRed, msg["result"])
+```
+
+Non-error result messages are silently skipped.
+
+---
+
+## 5. Tool Display
+
+### Tool Name Formatting
+
+The raw tool name from stream-JSON is title-cased for display:
+
+```go
+toolName := strings.ToUpper(name[:1]) + name[1:]
+```
+
+Example: `"tool_use"` name `"Bash"` → displayed as `"Bash"`.
+
+### Tool Input Parameter Extraction
+
+One input parameter is extracted per tool for the section content:
+
+| Tool Name  | Input Key     | What Is Shown                                                  |
+| ---------- | ------------- | -------------------------------------------------------------- |
+| `Bash`     | `command`     | Shell command being executed                                   |
+| `Read`     | `file_path`   | File being read                                                |
+| `Edit`     | `file_path`   | File being edited                                              |
+| `Write`    | `file_path`   | File being written                                             |
+| `Grep`     | `pattern`     | Search pattern                                                 |
+| `Glob`     | `pattern`     | Glob pattern                                                   |
+| `WebFetch` | `url`         | URL being fetched                                              |
+| `Task*`    | `description` | Task description (prefix match: `TaskCreate`, `TaskGet`, etc.) |
+| `Agent`    | `prompt`      | Agent prompt                                                   |
+
+Tools not in this table display with no content (header line only).
+
+The section color for all tool display is `colorGreen`.
+
+### Content Truncation
+
+If the extracted content contains more than one line, it is truncated:
+
+```
+<first line>
+... +N lines
+```
+
+Where `N` is `len(lines) - 1`. Single-line content is displayed as-is.
+
+---
+
+## 6. Lorah Status Messages
+
+These are printed by the loop (not by `printMessages`) to mark loop lifecycle events:
+
+| Event            | Label     | Color       | Content                                                  |
+| ---------------- | --------- | ----------- | -------------------------------------------------------- |
+| Loop start       | `"Lorah"` | `colorBlue` | `"Starting loop N..."` (N = iteration number)            |
+| Loop success     | `"Lorah"` | `colorBlue` | `"Loop N completed successfully"` (N = iteration number) |
+| First interrupt  | `"Lorah"` | `colorBlue` | `"Received interrupt, stopping after current loop..."`   |
+| Second interrupt | `"Lorah"` | `colorBlue` | `"Received second interrupt, shutting down..."`          |
+
+Error messages on failed iterations are printed directly to stderr (not via `printSection`):
+
+```
+<red>⏺ <bold>Error<reset>
+<error message>
+
+Retrying in 5s...
+
+```
+
+---
+
+## 7. Constants
+
+```go
+const (
+    colorReset = "\033[0m"
+    colorGreen = "\033[32m"
+    colorBlue  = "\033[34m"
+    colorBold  = "\033[1m"
+    colorRed   = "\033[31m"
+
+    maxBufferSize = 1024 * 1024 // 1MB buffer for JSON parsing
+)
+```
+
+These constants are package-level in `internal/loop/constants.go` and shared
+across `loop.go`, `claude.go`, and `output.go`. `retryDelay` is also defined
+in `constants.go` but is a loop concern — see [run.md](run.md).
+
+---
+
+## 8. Related Specifications
+
+- [run.md](run.md) — loop lifecycle that drives `printMessages` and status messages
+- [cli.md](cli.md) — CLI structure and entry point
diff --git a/docs/design/run.md b/docs/design/run.md
new file mode 100644
index 0000000..d81992f
--- /dev/null
+++ b/docs/design/run.md
@@ -0,0 +1,192 @@
+# Run Command Specification
+
+---
+
+## 1. Overview
+
+### Purpose
+
+The `run` command executes Claude Code CLI in an infinite loop, piping a prompt file
+to each invocation and displaying formatted stream-JSON output in real-time.
+The loop runs until interrupted; the agent manages its own workflow.
+
+### Goals
+
+- **Infinite loop**: runs until Ctrl+C or SIGTERM, no iteration limit
+- **Error recovery**: failed iterations sleep and retry automatically
+- **Signal handling**: first Ctrl+C/SIGTERM stops after current loop; second triggers immediate exit
+- **Flag passthrough**: all arguments after the prompt file passed to `claude` unchanged
+- **Real-time output**: stream-JSON parsed and displayed as it arrives
+
+### Non-Goals
+
+- Configurable retry strategy (exponential backoff, max retries, jitter)
+- Session persistence across process restarts
+- Multiple concurrent Claude invocations
+- Iteration limits or timeout
+
+---
+
+## 2. Interface
+
+### CLI
+
+```
+lorah run <prompt-file> [claude-flags...]
+```
+
+### Go Function
+
+```go
+// Run starts the infinite Claude Code CLI execution loop.
+// It handles signal interrupts and retries on error.
+// Run does not return under normal operation.
+func Run(promptFile string, claudeFlags []string)
+```
+
+`Run` is the only exported symbol from `internal/loop`.
+
+### Argument Handling (in `main.go`)
+
+Argument validation for `run` is handled by `runCmd` in `main.go`.
+See [cli.md section 4](cli.md#4-router-implementation) for the full behavior.
+`runCmd` calls `loop.Run(promptFile, claudeFlags)` after validation.
+
+---
+
+## 3. Loop Lifecycle
+
+### Constants
+
+```go
+retryDelay = 5 * time.Second
+```
+
+Defined in `internal/loop/constants.go` alongside the output constants.
+
+### Iteration Flow
+
+```go
+func Run(promptFile string, claudeFlags []string)
+```
+
+1. Create cancellable context and set up signal handler
+2. Initialize `iteration = 0`
+3. Loop:
+   1. Increment `iteration`
+   2. `printSection("Lorah", colorBlue, fmt.Sprintf("Starting loop %d...", iteration))`
+   3. Call `runClaude(ctx, promptFile, claudeFlags)`
+   4. On error: print error to stderr, sleep `retryDelay` (5s), continue
+   5. On success: `printSection("Lorah", colorBlue, fmt.Sprintf("Loop %d completed successfully", iteration))`, continue immediately
+
+### Signal Handling
+
+- A goroutine listens on a buffered channel for `os.Interrupt` and `syscall.SIGTERM`
+- On **first signal** (either `SIGINT` or `SIGTERM`):
+  1. Set a `stopping` flag (e.g. `atomic.Bool`)
+  2. Print blank line
+  3. `printSection("Lorah", colorBlue, "Received interrupt, stopping after current loop...")`
+  4. Do **not** cancel the context — let the current subprocess finish naturally
+- On **second signal** (any, while `stopping` is set):
+  1. Print blank line
+  2. `printSection("Lorah", colorBlue, "Received second interrupt, shutting down...")`
+  3. Call `cancel()` to propagate cancellation to any running subprocess
+  4. `os.Exit(0)`
+- After each successful or failed iteration, the loop checks `stopping`; if set, `os.Exit(0)`
+- Signal handling lives in `loop.go`, not `main.go`, because it is part of the loop lifecycle
+
+### Error Display
+
+Printed to stderr on a failed iteration:
+
+```
+<red>⏺ <bold>Error<reset>
+<error message>
+
+Retrying in 5s...
+
+```
+
+---
+
+## 4. Claude Code CLI Execution
+
+### Signature
+
+```go
+func runClaude(ctx context.Context, promptFile string, flags []string) error
+```
+
+### Subprocess Configuration
+
+1. Open `promptFile` for reading; return error if it cannot be opened
+2. Build argument list: `-p`, `--output-format`, `stream-json`, `--verbose`, then `flags...`
+3. `exec.CommandContext(ctx, "claude", args...)`
+4. `cmd.Stdin = file` — prompt file contents piped to stdin
+5. `cmd.Stderr = os.Stderr` — claude stderr passes through directly
+
+### Execution Steps
+
+1. Create stdout pipe via `cmd.StdoutPipe()`
+2. `cmd.Start()`
+3. `printMessages(stdout)` — blocking call that reads and formats stream-JSON in real-time
+4. `cmd.Wait()` — waits for subprocess to exit
+5. Return any error from `cmd.Wait()`
+
+### Error Sources
+
+| Source                        | Error Prefix                            |
+| ----------------------------- | --------------------------------------- |
+| Prompt file not readable      | `"opening prompt file: "`               |
+| stdout pipe creation failure  | `"creating stdout pipe: "`              |
+| `claude` not found in PATH    | `"starting Claude Code CLI: "`          |
+| Claude Code CLI non-zero exit | `"Claude Code CLI exited with error: "` |
+
+---
+
+## 5. Package Structure
+
+```
+internal/loop/
+  loop.go       -- Run() exported entry point, signal handling, infinite loop
+  claude.go     -- runClaude() subprocess execution
+  output.go     -- printMessages(), printSection() formatting
+  constants.go  -- ANSI colors, maxBufferSize, retryDelay
+```
+
+`internal/` ensures the package is not importable outside the module.
+A single `loop` package (not multiple sub-packages) because `printMessages`
+is only called from `runClaude`, and `runClaude` is only called from `Run`.
+Splitting further would require exporting symbols with no reason to be public.
+
+---
+
+## 6. Examples
+
+```sh
+# Basic usage
+lorah run prompt.md
+
+# With Claude settings file
+lorah run prompt.md --settings .lorah/settings.json
+
+# With specific model and turn limit
+lorah run prompt.md --model claude-opus-4-6 --max-turns 50
+
+# With multiple flags
+lorah run prompt.md --settings settings.json --model claude-opus-4-6 --verbose
+
+# Help
+lorah run --help
+
+# First Ctrl+C → prints "Received interrupt, stopping after current loop...", exits 0 after iteration
+# Second Ctrl+C → prints "Received second interrupt, shutting down...", exits 0 immediately
+```
+
+---
+
+## 7. Related Specifications
+
+- [cli.md](cli.md) — CLI routing and argument extraction for the `run` command
+- [output.md](output.md) — `printMessages` and `printSection` behavior
+- [task.md](task.md) — task management the agent uses within the run loop
diff --git a/docs/design/task.md b/docs/design/task.md
new file mode 100644
index 0000000..5bd4fe0
--- /dev/null
+++ b/docs/design/task.md
@@ -0,0 +1,607 @@
+# Task Command Specification
+
+---
+
+## 1. Overview
+
+### Purpose
+
+The `task` command provides CRUD operations for agent task management. Tasks are
+stored in a JSON file and queryable via CLI subcommands. Agents use task commands
+to read, claim, and complete work items efficiently without reading large markdown files.
+
+### Goals
+
+- **Token-efficient**: agents read only actionable tasks, not entire files
+- **Structured storage**: JSON backend with a defined schema
+- **Agent learning**: completion notes enable cross-iteration knowledge transfer
+- **Multiple output formats**: `markdown` (default) for agents and humans, `json` for scripting and non-LLM tooling
+- **Storage abstraction**: interface-based backend — JSON now, SQLite in the future
+
+### Non-Goals
+
+- SQLite backend (future work, after JSON proves out in practice)
+- Watch mode or live-updating markdown files
+- Multi-agent coordination or file locking
+- Migration tooling
+
+---
+
+## 2. Interface
+
+### CLI
+
+```
+lorah task <subcommand> [args...] [flags...]
+```
+
+### Subcommands
+
+| Subcommand | Arguments | Description                       |
+| ---------- | --------- | --------------------------------- |
+| `list`     |           | List tasks with optional filters  |
+| `get`      | `<id>`    | Get full details for a task       |
+| `create`   |           | Create a new task                 |
+| `update`   | `<id>`    | Update fields on an existing task |
+| `delete`   | `<id>`    | Delete a task                     |
+| `export`   |           | Export tasks to markdown          |
+
+---
+
+## 3. Task Schema
+
+### Phase and Section Types
+
+```go
+type Phase struct {
+    ID          string `json:"id"`
+    Name        string `json:"name,omitempty"`
+    Description string `json:"description,omitempty"`
+}
+
+type Section struct {
+    ID          string `json:"id"`
+    PhaseID     string `json:"phaseId"`
+    Name        string `json:"name,omitempty"`
+    Description string `json:"description,omitempty"`
+}
+```
+
+`ID` on `Phase` and `Section` is an auto-generated 8-char lowercase hex string (same format as task IDs). `Name` carries the human-readable label and may include ordinal prefixes for sorting and prioritization (e.g. `"Phase 1: Run Loop"`, `"1.1 Output Formatting"`). `Section.PhaseID` references the parent phase's hex ID.
+
+### Task Type
+
+```go
+type Task struct {
+    ID          string     `json:"id"`
+    Subject     string     `json:"subject"`
+    Status      TaskStatus `json:"status"`
+    PhaseID     string     `json:"phaseId,omitempty"`
+    SectionID   string     `json:"sectionId,omitempty"`
+    Notes       string     `json:"notes,omitempty"`
+    LastUpdated time.Time  `json:"lastUpdated"`
+}
+```
+
+### Status Type
+
+```go
+type TaskStatus string
+
+const (
+    StatusPending    TaskStatus = "pending"
+    StatusInProgress TaskStatus = "in_progress"
+    StatusCompleted  TaskStatus = "completed"
+)
+```
+
+### TaskList (File Root)
+
+```go
+type TaskList struct {
+    Name        string        `json:"name,omitempty"`
+    Description string        `json:"description,omitempty"`
+    Phases      []Phase       `json:"phases,omitempty"`
+    Sections    []Section     `json:"sections,omitempty"`
+    Tasks       []Task        `json:"tasks"`
+    Version     string        `json:"version"`
+    LastUpdated time.Time     `json:"lastUpdated"`
+}
+```
+
+### Field Descriptions
+
+| Field         | Type    | Purpose                                                   |
+| ------------- | ------- | --------------------------------------------------------- |
+| `name`        | string  | Project name; rendered as H1 in markdown export           |
+| `description` | string  | Project description; rendered below H1 in markdown export |
+| `id`          | string  | Unique identifier; auto-generated 8-char lowercase hex    |
+| `subject`     | string  | Brief, actionable title in imperative form                |
+| `status`      | enum    | `pending`, `in_progress`, `completed`                     |
+| `phaseId`     | string  | Hex ID of the parent `Phase` entry                        |
+| `sectionId`   | string  | Hex ID of the parent `Section` entry                      |
+| `notes`       | string  | Markdown-formatted notes for agent learning               |
+| `lastUpdated` | ISO8601 | Timestamp updated automatically on every create or update |
+
+---
+
+## 4. Storage
+
+### Interface
+
+```go
+type Storage interface {
+    Load() (*TaskList, error)
+    Save(list *TaskList) error
+    Get(id string) (*Task, error)
+    List(filter Filter) ([]Task, error)
+    Create(task *Task) error
+    Update(task *Task) error
+    Delete(id string) error
+}
+```
+
+### Filter
+
+```go
+type Filter struct {
+    Status  []TaskStatus
+    PhaseID   string
+    SectionID string
+    Limit   int
+}
+```
+
+Filters are AND-combined. `Limit = 0` means no limit.
+
+### JSON Backend Behavior
+
+- File: `tasks.json` in the working directory
+- Thread safety: `sync.RWMutex` (read lock on `Load`, write lock on `Save`)
+- Non-existent file on `Load`: returns an empty `TaskList` with `Version: "1.0"` (not an error)
+- Duplicate `id` on `Create`: returns an error
+- `Save` updates `LastUpdated` to the current time before writing
+- Writes with `json.MarshalIndent` for human readability
+
+### Example File
+
+```json
+{
+  "name": "Lorah Development Plan",
+  "description": "Track progress on the Lorah infinite-loop harness implementation.",
+  "phases": [
+    {
+      "id": "d4e5f6a7",
+      "name": "Phase 1: Run Loop",
+      "description": "Implement the infinite loop, subprocess execution, and output formatting."
+    },
+    {
+      "id": "e8f9a0b1",
+      "name": "Phase 2: Task Management",
+      "description": "Implement the task management system for agent workflow coordination."
+    }
+  ],
+  "sections": [
+    {
+      "id": "b8c9d0e1",
+      "phaseId": "d4e5f6a7",
+      "name": "1.1 Output Formatting",
+      "description": "Stream-JSON parsing and color-coded terminal output."
+    },
+    {
+      "id": "f2a3b4c5",
+      "phaseId": "d4e5f6a7",
+      "name": "1.2 Signal Handling"
+    }
+  ],
+  "tasks": [
+    {
+      "id": "a3f7b2c1",
+      "subject": "Implement stream-JSON output parsing",
+      "status": "completed",
+      "phaseId": "d4e5f6a7",
+      "sectionId": "b8c9d0e1",
+      "notes": "Scans stdout line-by-line as newline-delimited JSON. Skips empty lines and parse failures gracefully.",
+      "lastUpdated": "2026-03-10T14:22:00Z"
+    },
+    {
+      "id": "b8e4d1f0",
+      "subject": "Add color-coded section headers",
+      "status": "in_progress",
+      "phaseId": "d4e5f6a7",
+      "sectionId": "b8c9d0e1",
+      "lastUpdated": "2026-03-10T13:00:00Z"
+    },
+    {
+      "id": "c2a9e5b3",
+      "subject": "Add usage examples to README",
+      "status": "pending",
+      "lastUpdated": "2026-03-10T12:00:00Z"
+    }
+  ],
+  "version": "1.0",
+  "lastUpdated": "2026-03-10T15:00:00Z"
+}
+```
+
+Notes:
+
+- `name` and `description` are optional `omitempty` fields on the `TaskList`; they are absent when empty
+- `phases` and `sections` are lookup tables for display names and descriptions used in markdown export headings; they are populated via `--phase-name`/`--phase-description`/`--section-name`/`--section-description` on `create` and `update`; phase and section IDs are auto-generated 8-char hex
+- `description` on phases and sections is optional; it captures goals or context (e.g. what the phase aims to accomplish, what packages it covers) and is rendered below the heading in markdown export
+- A task's `phaseId`/`sectionId` fields are bare ID strings; there is no referential integrity — a task can reference a phase not in the `phases` array and vice versa
+- `omitempty` fields (`phaseId`, `sectionId`, `notes`) are absent when empty (see `c2a9e5b3`)
+- `status` must be one of the defined `TaskStatus` values: `pending`, `in_progress`, `completed`
+- `lastUpdated` on tasks is set automatically on every `Create` or `Update`; it is always present
+- `version` is set to `"1.0"` on first write and never changed; it is a forward-looking schema marker for future migration tooling
+- `lastUpdated` on the `TaskList` root is set to the current time on every `Save()`; it is not consumed by any subcommand
+
+---
+
+## 5. Flag Parsing
+
+Each subcommand parses its own flags using `flag.NewFlagSet` (stdlib):
+
+```go
+fs := flag.NewFlagSet("lorah task list", flag.ContinueOnError)
+var statuses multiFlag
+fs.Var(&statuses, "status", "filter by status (repeatable)")
+format := fs.String("format", "markdown", "output format")
+// ...
+fs.Parse(args)
+```
+
+`multiFlag` is a `[]string` type implementing `flag.Value` (`String()` and `Set()` methods).
+It is used for any flag that can be specified more than once. `flag.String` cannot support
+repeatable flags — each call to `Set` overwrites the previous value.
+
+`flag.ContinueOnError` is used so the handler can print custom usage on error.
+Unknown flags exit 1 with a usage message. This is stdlib — no external library.
+
+For `update`'s partial-update semantics, use `fs.Visit` after `fs.Parse` to enumerate
+only the flags that were explicitly provided:
+
+```go
+provided := map[string]bool{}
+fs.Visit(func(f *flag.Flag) { provided[f.Name] = true })
+```
+
+Only update a field on the task if `provided["<flag-name>"]` is true. This is the correct
+approach because it allows `--subject=""` to clear the subject field. Do not use an empty
+string as a sentinel for "not provided" — that makes it impossible to clear string fields.
+
+---
+
+## 6. Subcommand Behavior
+
+### `list`
+
+```
+lorah task list [--status=STATUS] [--phase=P] [--section=S] [--limit=N] [--flat] [--format=json|markdown]
+```
+
+- Default format: `markdown`
+- `--status` is repeatable to filter by multiple statuses
+- Results ordered by phase, then section (ordered by position in the `phases`/`sections` arrays), then task insertion order
+- `--flat`: suppresses phase and section headings; outputs a flat bullet list of tasks. Only applies to markdown format; ignored when `--format=json`
+
+### `get`
+
+```
+lorah task get <id> [--format=json|markdown]
+```
+
+- Default format: `markdown`
+- Exits 1 with an error message if the task ID is not found
+
+### `create`
+
+```
+lorah task create --subject="..." [--status=STATUS] [--phase=P] [--phase-name="..."] [--phase-description="..."] [--section=S] [--section-name="..."] [--section-description="..."] [--project-name="..."] [--project-description="..."]
+```
+
+- `--subject` is required
+- Auto-generates a unique 8-character lowercase hex ID (e.g. `"a3f7b2c1"`)
+- Default status: `pending`
+- Exits 1 if `--status` is not a valid `TaskStatus` (`pending`, `in_progress`, `completed`)
+- Sets `lastUpdated` to the current time
+- Prints the new task's ID to stdout on success (one line per created entity; see output format below)
+- `--phase` assigns the task to an existing phase by hex ID
+- `--phase-name` sets the phase name; if `--phase` is omitted, auto-generates a new phase hex ID and creates it
+- `--phase-description` sets the phase description; follows the same `--phase`/auto-generate rules as `--phase-name`
+- `--section` assigns the task to an existing section by hex ID; requires a phase context (`--phase` or auto-generated via `--phase-name`)
+- `--section-name` sets the section name; if `--section` is omitted, auto-generates a new section hex ID and creates it; requires a phase context (`--phase` or auto-generated via `--phase-name`)
+- `--section-description` sets the section description; follows the same `--section`/auto-generate rules as `--section-name`
+- `--project-name` sets the `name` field on the `TaskList`
+- `--project-description` sets the `description` field on the `TaskList`
+- Output on success (one line per created entity, only lines for newly created entities are printed):
+
+  ```
+  phase <hex-id>
+  section <hex-id>
+  task <hex-id>
+  ```
+
+### `update`
+
+```
+lorah task update <id> [--status=STATUS] [--subject="..."] [--phase=P] [--phase-name="..."] [--phase-description="..."] [--section=S] [--section-name="..."] [--section-description="..."] [--notes="..."] [--project-name="..."] [--project-description="..."]
+```
+
+- Partial update: only provided flags are changed; omitted fields are unchanged
+- Exits 1 if task not found
+- Exits 1 if `--status` is not a valid `TaskStatus` (`pending`, `in_progress`, `completed`)
+- Always sets `lastUpdated` to the current time
+- `--notes` sets (replaces) the `notes` field; the caller is responsible for appending if needed
+- `--phase` reassigns the task to an existing phase by hex ID
+- `--phase-name` upserts the name on the phase referenced by `--phase`; requires `--phase`
+- `--phase-description` upserts the description on the phase referenced by `--phase`; requires `--phase`
+- `--section` reassigns the task to an existing section by hex ID; requires `--phase`
+- `--section-name` upserts the name on the section referenced by `--section`; requires `--section`
+- `--section-description` upserts the description on the section referenced by `--section`; requires `--section`
+- `--project-name` sets the `name` field on the `TaskList`
+- `--project-description` sets the `description` field on the `TaskList`
+
+### `delete`
+
+```
+lorah task delete <id>
+```
+
+- Exits 1 with error message if task not found
+- No output on success
+- Returns 0
+
+### `export`
+
+```
+lorah task export [--output=FILE] [--status=STATUS]
+```
+
+- Outputs to stdout unless `--output` specifies a file path
+- `--status` is repeatable; when provided, only tasks matching any of the specified statuses are included
+- Renders markdown (see Output Formats section)
+
+---
+
+## 7. Output Formats
+
+### Single-Task Markdown (for `get`)
+
+```markdown
+# Implement stream-JSON output parsing
+
+**Status:** completed
+**Phase:** Phase 1: Run Loop
+**Section:** 1.1 Output Formatting
+**Updated:** 2026-03-10T14:22:00Z
+
+Scans stdout line-by-line as newline-delimited JSON. Skips empty lines and parse failures gracefully.
+```
+
+Rules:
+
+- H1 heading is the task `subject`
+- `status` is always shown
+- `lastUpdated` is always shown (it is always set)
+- Optional fields (`phaseId`, `sectionId`) are omitted when empty; when present, render the phase/section name if available, otherwise the hex ID
+- `notes` printed as-is below the field list, separated by a blank line; if `notes` is empty, print `**Notes:** (none)`
+
+### Single-Task JSON (for `get`)
+
+```json
+{
+  "id": "a3f7b2c1",
+  "subject": "Implement stream-JSON output parsing",
+  "status": "completed",
+  "phaseId": "d4e5f6a7",
+  "sectionId": "b8c9d0e1",
+  "notes": "Scans stdout line-by-line as newline-delimited JSON. Skips empty lines and parse failures gracefully.",
+  "lastUpdated": "2026-03-10T14:22:00Z"
+}
+```
+
+A single task object with all fields present. Not wrapped in a `{"tasks": [...]}` envelope — `get` returns the task directly, not a list.
+
+### List Markdown (for `list`)
+
+The `list` subcommand renders markdown using the same grouped structure as `export`: phase H2 headings, section H3 headings, and bullet list items. Output is scoped to the filtered results — phases and sections with zero matching tasks are omitted. The list and export markdown formatters share the same rendering logic.
+
+Project name/description H1 is **not** rendered in `list` output (only in `export`).
+
+Tasks with a non-empty `notes` field render the notes in a fenced code block with `notes` info string, indented 2 spaces, on the line after the task bullet. Tasks without notes render as bare bullets.
+
+Example (`lorah task list --status=pending --phase=d4e5f6a7`):
+
+````markdown
+## Phase 1: Run Loop
+
+### 1.1 Output Formatting
+
+- `d6e7f8a9` [pending] Add tool input truncation
+
+  ```notes
+  Tool inputs currently show full content. Need to truncate to 1 line
+  with `... +N lines` indicator. See output.md spec for details.
+  ```
+
+### 1.2 Signal Handling
+
+- `c1d2e3f4` [pending] Implement two-signal graceful shutdown
+````
+
+#### Flat Mode (`--flat`)
+
+When `--flat` is passed, phase and section headings are suppressed and notes are omitted. Output is a flat bullet list:
+
+```markdown
+- `d6e7f8a9` [pending] Add tool input truncation
+- `c1d2e3f4` [pending] Implement two-signal graceful shutdown
+```
+
+Useful when agents want minimal tokens and the grouping context is unnecessary.
+
+### JSON (for scripting)
+
+```json
+{
+  "tasks": [
+    {
+      "id": "a3f7b2c1",
+      "subject": "Implement stream-JSON output parsing",
+      "status": "completed",
+      "phaseId": "d4e5f6a7",
+      "sectionId": "b8c9d0e1",
+      "notes": "Scans stdout line-by-line as newline-delimited JSON. Skips empty lines and parse failures gracefully.",
+      "lastUpdated": "2026-03-10T14:22:00Z"
+    }
+  ]
+}
+```
+
+Full task objects, suitable for programmatic parsing.
+
+### Markdown Export (for `export`)
+
+````markdown
+# Lorah Development Plan
+
+Track progress on the Lorah infinite-loop harness implementation.
+
+## Phase 1: Run Loop
+
+Implement the infinite loop, subprocess execution, and output formatting.
+
+### 1.1 Output Formatting
+
+Stream-JSON parsing and color-coded terminal output.
+
+- `a3f7b2c1` [completed] Implement stream-JSON output parsing
+
+  ```notes
+  Scans stdout line-by-line as newline-delimited JSON. Skips empty lines
+  and parse failures gracefully.
+  ```
+
+- `b8e4d1f0` [completed] Add color-coded section headers
+- `d6e7f8a9` [pending] Add tool input truncation
+
+### 1.2 Signal Handling
+
+- `c1d2e3f4` [pending] Implement two-signal graceful shutdown
+````
+
+Grouped by phase (H2) then section (H3). Status is rendered inline in brackets after the task ID.
+
+Project heading rules:
+
+- If `name` is set: render `# {name}` as the first line
+- If `description` is set (and `name` is set): render as a plain paragraph after the H1, followed by a blank line before the first phase heading
+- If `name` is not set: no H1 heading (export starts directly at phase headings)
+- If `description` is set but `name` is not: skip
+
+Phase and section heading rules:
+
+- Phase with name: `## {name}`; without name: `## {id}` (hex fallback)
+- Section with name: `### {name}`; without name: `### {id}` (hex fallback)
+- If a phase or section has a `description`, render it as a plain paragraph on the line after the heading, followed by a blank line before the task list
+- If there is no `description`, omit the paragraph entirely (no blank placeholder)
+
+Tasks with no `phase` are collected under `## (none)`.
+Tasks with no `section` appear directly under the phase heading with no H3 sub-heading.
+
+Task note rules:
+
+- If a task has a non-empty `notes` field, render a blank line after the task bullet, then a fenced code block with `notes` info string indented 2 spaces (opening fence, all content lines, closing fence)
+- The notes content is rendered verbatim inside the fence
+- The 2-space indent keeps the code block part of the list item, preserving list structure
+- Tasks without notes render as bare bullets with no extra lines
+
+---
+
+## 8. Agent Integration
+
+### Recommended Workflow
+
+1. `lorah task list --status=pending` — scan available tasks
+2. `lorah task get <id>` — read full details for the chosen task
+3. `lorah task update <id> --status=in_progress` — claim the task
+4. _(agent does the work)_
+5. `lorah task update <id> --status=completed --notes="..."` — record what happened
+
+### Learning from Prior Work
+
+Before starting work on a related task, review recent completions:
+
+```
+
+lorah task list --status=completed --phase=<phase-hex-id> --limit=5
+
+```
+
+Completion notes should include: what worked, issues encountered, related files changed,
+and any follow-up observations. This enables future iterations to avoid repeating mistakes
+and build on prior context without re-reading the codebase from scratch.
+
+---
+
+## 9. Package Structure
+
+```
+
+internal/task/
+task.go -- Phase, Section, Task, TaskStatus, TaskList, Filter types
+storage.go -- Storage interface
+json_storage.go -- JSONStorage implementation
+format.go -- Output formatters: json, markdown
+cmd.go -- CLI subcommand dispatch and handlers
+
+```
+
+`internal/` ensures the package is not importable outside the module.
+
+---
+
+## 10. Examples
+
+```sh
+# List pending tasks (agent workflow)
+lorah task list --status=pending
+
+# List pending tasks (flat, for minimal tokens)
+lorah task list --status=pending --flat
+
+# Get full task details
+lorah task get a3f7b2c1
+
+# Get full task details as JSON (for scripting)
+lorah task get a3f7b2c1 --format=json
+
+# Create first task in a new phase and section (auto-generates phase/section IDs)
+# Output:
+#   phase d4e5f6a7
+#   section b8c9d0e1
+#   task a3f7b2c1
+lorah task create --subject="Implement stream-JSON output parsing" --project-name="Lorah Development Plan" --project-description="Track progress on the Lorah infinite-loop harness implementation." --phase-name="Phase 1: Run Loop" --phase-description="Implement the infinite loop, subprocess execution, and output formatting." --section-name="1.1 Output Formatting" --section-description="Stream-JSON parsing and color-coded terminal output."
+
+# Create subsequent tasks in the same phase/section (IDs from previous output)
+lorah task create --subject="Add color-coded section headers" --phase=d4e5f6a7 --section=b8c9d0e1
+
+# Claim and complete a task
+lorah task update a3f7b2c1 --status=in_progress
+lorah task update a3f7b2c1 --status=completed --notes="Scans stdout line-by-line as newline-delimited JSON. Skips empty lines and parse failures gracefully."
+
+# Human review (markdown export)
+lorah task export --output=PROGRESS.md
+
+# Filter by phase
+lorah task list --phase=d4e5f6a7 --status=pending --limit=10
+```
+
+---
+
+## 11. Related Specifications
+
+- [cli.md](cli.md) — top-level routing to the `task` subcommand
+- [run.md](run.md) — the run loop that agents use to process tasks
+- [output.md](output.md) — output system (`task` uses its own formatters, not `printMessages`)
diff --git a/examples/.lorah/prompt.md b/examples/.lorah/prompt.md
new file mode 100644
index 0000000..1b3634d
--- /dev/null
+++ b/examples/.lorah/prompt.md
@@ -0,0 +1,78 @@
+# TDD Implementation Agent
+
+You are a TDD implementation agent for the `lorah` project. Your job is to complete exactly **one task** per invocation — either write tests OR write implementation code. Never both.
+
+IMPORTANT: overzealous agents began implementing phase 4 (task management) before we were ready. Once you begin phase 4, pay special attention to what is already written. Do NOT assume it is well written or written to spec. You will likely need to refactor tests and code to bring it in conformity with our design specs.
+
+---
+
+## Workflow
+
+1. **Orient** — Run `git log --oneline -10` to understand what was done in prior iterations.
+
+2. **Select** — Read `.lorah/tasks.md`. Find the first `[pending]` or `[in_progress]` task in document order. That is your task for this invocation.
+
+3. **Start** — If the task is `[pending]`, change it to `[in_progress]` in `.lorah/tasks.md`.
+
+4. **Understand** — Read the task's notes block for implementation guidance. Consult the relevant spec in `docs/design/` for detailed requirements. Read `CLAUDE.md` for project conventions.
+
+5. **Do the work** — Exactly one of the following:
+   - **Test task** ("Write tests for…"): Write tests only. Do not write any production/implementation code. Add stubs or interface definitions only if required to make tests compilable.
+
+   - **Implementation task** ("Implement…"): Write production code to make the preceding tests pass. Do not write any new tests. If you discover the existing tests conflict with the spec, follow the **Blocked workflow** below instead.
+
+   - **Other task** (e.g., Makefile target, config change): Do what the task describes. No tests needed unless explicitly stated.
+
+6. **Verify** — Run all three in order, fix any issues before proceeding:
+   - `make fmt`
+   - `make lint`
+   - `make test`
+     - Test tasks: failures are expected (no implementation yet), but panics and compilation errors must be fixed.
+     - Implementation tasks: all tests must pass.
+
+7. **Update tasks.md**:
+   - Change the task status from `[in_progress]` to `[completed]`.
+   - Append notes to the completed task with anything useful for future agents (files created, patterns used, gotchas).
+   - If you discovered context relevant to the _next_ pending task, add it to that task's notes block.
+
+8. **Commit** — Stage all changed files and commit with a conventional commit message (e.g., `test(loop): add loop lifecycle tests`, `feat(loop): implement loop lifecycle and signal handling`).
+
+9. **Exit** — Stop. Do NOT proceed to the next task.
+
+---
+
+## Blocked workflow
+
+If you are on an **implementation task** and discover the existing tests conflict with the design spec:
+
+1. Discard all uncommitted changes: `git checkout .`
+2. In `.lorah/tasks.md`:
+   - Mark the implementation task as `[blocked]` with notes explaining the spec conflict
+   - Mark the preceding test task back to `[in_progress]`
+3. Exit — do not commit anything
+
+The next iteration will pick up the `[in_progress]` test task and fix the tests. That agent should, when done:
+
+- Mark the test task `[completed]`
+- Change the `[blocked]` implementation task back to `[pending]`
+
+---
+
+## Rules
+
+- **Strict TDD boundary**: test tasks contain ONLY test code; implementation tasks contain ONLY production code. No exceptions.
+- **One task per invocation**: complete one task, commit, exit.
+- **Stdlib only**: no external dependencies — Go standard library only.
+- **Design docs are authoritative**: `docs/design/cli.md`, `run.md`, `output.md`, `task.md` define the target behavior.
+- **If blocked for other reasons**: add a note to the task explaining why, leave it as `[pending]`, and exit without committing.
+
+---
+
+## Tasks.md status values
+
+```
+[pending]     → not started
+[in_progress] → actively being worked (current or interrupted iteration)
+[completed]   → done
+[blocked]     → implementation blocked by incorrect tests; see Blocked workflow
+```
diff --git a/examples/.lorah/settings.json b/examples/.lorah/settings.json
new file mode 100644
index 0000000..edbacab
--- /dev/null
+++ b/examples/.lorah/settings.json
@@ -0,0 +1,11 @@
+{
+  "model": "sonnet",
+  "permissions": {
+    "defaultMode": "bypassPermissions"
+  },
+  "sandbox": {
+    "enabled": true,
+    "autoAllowBashIfSandboxed": true
+  },
+  "includeCoAuthoredBy": false
+}
diff --git a/examples/.lorah/tasks.md b/examples/.lorah/tasks.md
new file mode 100644
index 0000000..29d8bca
--- /dev/null
+++ b/examples/.lorah/tasks.md
@@ -0,0 +1,961 @@
+# Lorah
+
+Implementation plan for lorah, a CLI harness for autonomous coding agents.
+
+## 1. Infrastructure
+
+Prerequisites for TDD: test tooling and build system setup.
+
+- [completed] Add `make test` target to Makefile
+
+  ```notes
+  - Run `go test ./...`
+  - Add `test` to the `.PHONY` declaration
+  - Update the help text
+  - Prerequisite for all TDD work that follows
+  - Added `test` target running `go test ./...`, added to `.PHONY` and help text
+  ```
+
+## 2. CLI Router
+
+Refactor `main.go` from a monolithic program into a thin subcommand router per `cli.md`. Introduces `lorah run <prompt-file>` and `lorah task` subcommands while keeping existing loop logic in place for subsequent features to migrate into `internal/loop/`.
+
+### Routing
+
+- [completed] Write tests for CLI routing
+
+  ```notes
+  - Extract a testable `route(args []string, version string, runFn func(string, []string) error, taskFn func([]string) error) int` function
+  - Test: `--version`/`-V` prints version to stdout and returns 0
+  - Test: `--help`/`-h` prints usage to stderr and returns 0
+  - Test: no args prints usage to stderr and returns 1 (per cli.md, distinct from `--help`: `--help` exits 0, no-args exits 1)
+  - Test: `run <file>` calls runFn with prompt file and remaining flags
+  - Test: `task <subcommand>` calls taskFn
+  - Test: unknown subcommand prints error to stderr and returns 1
+  - Test in `main_test.go` — test routing logic directly, no subprocess overhead
+  - Tests written in `main_test.go`; minimal `route()` stub added to `main.go` for compilation
+  - Uses `captureOutput()` helper with `os.Pipe()` to capture stdout/stderr
+  - All tests fail as expected (stub returns 0, never calls handlers)
+  ```
+
+- [completed] Implement CLI routing refactor
+
+  ```notes
+  - Extract `route()` from `main()` matching the signature used in tests
+  - Add `run` subcommand wrapping existing loop logic inline
+  - Add `task` stub (prints "not yet implemented" to stderr, returns 1)
+  - Update help text for `lorah run <prompt-file> [claude-flags...]` and `lorah task <subcommand>` per `cli.md`
+  - Keep all existing loop and output logic in `main.go` for now — subsequent features migrate to `internal/loop/`
+  - Implemented in `main.go`: `route()`, `runCmd()`, `taskCmd()`, `printUsage()`, `printRunUsage()`, `printTaskUsage()`
+  - `main()` now calls `os.Exit(route(os.Args[1:], Version, runCmd, taskCmd))`
+  - Fixed tool name formatting bug: `strings.ToUpper(name[:1]) + name[1:]` (not `ToLower` on remainder)
+  - All 6 routing tests pass
+  ```
+
+## 3. Run Loop
+
+Migrate the infinite loop, subprocess execution, and constants from `main.go` into `internal/loop/` per `run.md`.
+
+### Loop Lifecycle and Signal Handling
+
+- [completed] Write tests for loop lifecycle and signal handling
+
+  ```notes
+  - Test in `internal/loop/loop_test.go`
+  - Test `Run()` by injecting a fake `runFn` to verify:
+    - Iteration counter increments
+    - `printSection` called for start and success
+    - Loop continues on success
+  - Test error handling: on `runFn` error, error printed to stderr, `retryDelay` sleep occurs, loop continues
+  - Test stopping flag: loop exits after current iteration when `stopping` is set
+  - Test two-signal shutdown:
+    - First signal sets `stopping` flag and prints interrupt message
+    - Second signal calls `cancel()` and exits immediately
+  - Use `os.Signal` channels to simulate `SIGINT` in tests
+  - `constants.go` values are trivial — no dedicated test needed
+  - Tests written in `internal/loop/loop_test.go` with `captureOutput()` helper
+  - Minimal stubs in `internal/loop/loop.go` and `internal/loop/constants.go` for compilation
+  - Internal API: `run(ctx, cancel, promptFile, flags, runFn, stopping, delay)` and `handleSignals(sigCh, stopping, cancel, exitFn)`
+  - `run()` returns when stopping is set (no os.Exit); `Run()` will call os.Exit after run() returns
+  - `handleSignals()` uses `stopping.Swap(true)` to distinguish first vs second signal; takes `exitFn func(int)` instead of `os.Exit` directly for testability
+  - All 7 tests fail as expected (stubs are no-ops); no panics or compile errors
+  ```
+
+- [completed] Implement loop lifecycle and signal handling
+
+  ```notes
+  - Create `internal/loop/constants.go`:
+    - ANSI color constants: `colorReset`, `colorGreen`, `colorBlue`, `colorBold`, `colorRed`
+    - `maxBufferSize` (1MB)
+    - `retryDelay` (5s)
+  - Create `internal/loop/loop.go` with `Run(promptFile, claudeFlags)`:
+    - Cancellable context
+    - Signal handler goroutine: buffered channel, `atomic.Bool stopping`
+    - First signal: sets `stopping`, prints interrupt message
+    - Second signal: calls `cancel()` and `os.Exit(0)`
+    - Infinite loop with iteration counter
+    - `printSection` for start and success
+    - Error display to stderr with `retryDelay` sleep
+    - Stop-after-iteration check per run.md §3
+  - Update `main.go` `runCmd` to call `loop.Run()` instead of inlining loop logic
+  - Added stub `internal/loop/claude.go` with placeholder `runClaude` (returns "not yet implemented") — needed for `Run()` to compile; full implementation in subsequent task
+  - Added stub `internal/loop/output.go` with minimal `printSection` — needed for `run()` and `handleSignals()` to compile; tests and full implementation in subsequent tasks
+  - Removed `os/signal` and `syscall` imports from `main.go` (no longer used after inline loop removal)
+  - `runClaude` and `printMessages` remain in `main.go` as dead code — will be removed when stream-JSON output task migrates them to `internal/loop/output.go` and `internal/loop/claude.go`
+  - All 7 loop tests pass
+  ```
+
+### Subprocess Execution
+
+- [completed] Write tests for subprocess execution
+
+  ```notes
+  - Test in `internal/loop/claude_test.go`
+  - Test `runClaude()` using the `TestHelperProcess` pattern (`os.Args[0]` re-exec):
+    - Correct args passed to `claude`: `-p`, `--output-format`, `stream-json`, `--verbose`, plus passthrough flags
+    - Prompt file piped to stdin
+    - Error returned on non-zero exit
+  - Test error cases:
+    - Missing prompt file returns error prefixed `"opening prompt file:"`
+    - Failed subprocess returns error prefixed `"Claude Code CLI exited with error:"`
+  - Added `var execCommandContext = exec.CommandContext` stub to `claude.go` for test overriding
+  - `TestHelperProcess` supports env vars: `GO_TEST_HELPER_PROCESS`, `GO_TEST_ARGS_FILE`, `GO_TEST_STDIN_FILE`, `GO_TEST_EXIT_CODE`
+  - `helperClaudeFunc(extraEnv...)` is a reusable helper that builds the override function
+  - All 4 tests fail as expected (stub returns "not yet implemented"); no panics or compile errors
+  ```
+
+- [completed] Implement subprocess execution
+
+  ```notes
+  - Create `internal/loop/claude.go` with `runClaude(ctx, promptFile, flags)`:
+    - Opens prompt file (error prefix: `"opening prompt file:"`)
+    - Builds args: `-p`, `--output-format`, `stream-json`, `--verbose`, `flags...`
+    - `exec.CommandContext` with `StdoutPipe`
+    - `cmd.Stdin = file`, `cmd.Stderr = os.Stderr`, `cmd.Env = os.Environ()`
+    - Calls `printMessages(stdout)`
+    - Returns `cmd.Wait()` error prefixed per run.md §4 (`"Claude Code CLI exited with error:"`)
+  - Do NOT set `cmd.Env = os.Environ()` — in Go, nil Env inherits parent environment (same behavior),
+    and setting it explicitly would overwrite env vars injected by the test helper on the returned cmd.
+  - Added stub `printMessages(r io.Reader)` to `output.go` (reads and discards) — needed for
+    compilation; full implementation in the subsequent stream-JSON output task.
+  - All 4 subprocess tests pass.
+  ```
+
+### Stream-JSON Parsing and Output
+
+- [completed] Write tests for stream-JSON parsing and formatted output
+
+  ```notes
+  - Test `printSection(label, color, content string)`:
+    - ANSI output: colored icon, bold label, reset, trimmed content, trailing blank line
+    - Empty content omits content line but still prints trailing blank line
+  - Test `printMessages(r io.Reader)` — feed newline-delimited JSON via `strings.NewReader`:
+    - `assistant`/`text` → `printSection("Claude", "", text)`
+    - `assistant`/`thinking` → `printSection("Claude (thinking)", "", thinking)`
+    - `assistant`/`tool_use` for each known tool name → correct label and extracted input key
+    - Unknown tool → header only, no content
+    - `result` with `is_error=true` → `printSection("Result (error)", colorRed, result)`
+    - Non-error `result` → silently skipped
+    - Unknown message type → silently skipped
+    - Malformed JSON line → silently skipped
+    - Multi-line tool input → first line + `"... +N lines"` truncation
+  - Capture stdout in tests using `os.Pipe()` or a `bytes.Buffer` passed via writer injection
+  - Tests written in `internal/loop/output_test.go`; uses existing `captureOutput()` helper from `loop_test.go`
+  - `printSection` tests PASS (stub already has correct implementation)
+  - `printMessages` tests FAIL as expected (stub discards all input); no panics or compile errors
+  - JSON format for assistant messages: `{"type":"assistant","message":{"content":[...]}}`
+  - JSON format for result messages: `{"type":"result","is_error":true,"result":"..."}`
+  - Tool input is nested under `"input"` key as a JSON object: `{"command":"ls"}`, `{"file_path":"/foo"}`, etc.
+  ```
+
+- [completed] Implement stream-JSON parsing and formatted output
+
+  ```notes
+  - Create `internal/loop/output.go`:
+    - `printSection(label, color, content string)`: writes `color+icon+reset+" "+bold+label+reset+newline`, then trimmed content (if non-empty), then blank line
+    - `printMessages(r io.Reader)`: `bufio.Scanner` with buffer up to `maxBufferSize`; skips empty lines and JSON parse failures
+    - Dispatch on `msg["type"]`:
+      - `"assistant"` → iterate content blocks, dispatch on `block["type"]` (`text`/`thinking`/`tool_use`)
+      - `"result"` → if `is_error`, print error section; otherwise silently skip
+      - Others → silently skip
+    - Tool display: title-case via `strings.ToUpper(name[:1])+name[1:]` — do NOT use `ToLower` on the remainder (current `main.go` bug breaks `"WebFetch"` → `"Webfetch"`)
+    - Extract input key via lookup table: `Bash→command`, `Read/Edit/Write→file_path`, `Grep/Glob→pattern`, `WebFetch→url`, `Task→description`, `Agent→prompt`
+    - Truncate multi-line content: first line + `"... +N lines"`
+  - Removed equivalent dead code from `main.go`: `printSection`, `runClaude`, `printMessages` functions and their associated constants and imports
+  - All 10 output tests pass (2 printSection + 8 printMessages)
+  ```
+
+---
+
+## 4. Task Management
+
+Implement the `lorah task` subcommand system per `task.md`. Provides CRUD operations for agent task management with JSON storage backend and multiple output formats. All code lives in `internal/task/` (unexported package). Design spec: `docs/design/task.md`.
+
+### Core Types
+
+- [completed] Write tests for core types (task.go)
+
+  ```notes
+  - Test in `internal/task/task_test.go`
+  - Test TaskStatus constants: `StatusPending` = `"pending"`, `StatusInProgress` = `"in_progress"`, `StatusCompleted` = `"completed"`
+  - Test Phase JSON serialization: `ID` always present; `Name` and `Description` use `omitempty` (absent when empty)
+  - Test Section JSON serialization: `ID` and `PhaseID` always present; `Name` and `Description` use `omitempty`
+  - Test Task JSON serialization: `ID`, `Subject`, `Status`, `LastUpdated` always present; `PhaseID`, `SectionID`, `Notes` use `omitempty` (absent when empty)
+  - Test Task JSON deserialization round-trip: marshal → unmarshal with all fields populated, verify equality
+  - Test TaskList JSON serialization: `Tasks`, `Version`, `LastUpdated` always present; `Name`, `Description`, `Phases`, `Sections` use `omitempty`
+  - Test generateID(): returns 8-character string, all characters are lowercase hex (`[0-9a-f]`)
+  - Test generateID() uniqueness: call multiple times, verify all results are distinct
+  - Add minimal type stubs in `internal/task/task.go` for compilation (types with zero-value fields, `generateID()` returning `""`)
+  - Expect: type/serialization tests pass against stubs (correct JSON tags); generateID tests fail (stub returns `""`)
+  - NOTE: Overzealous prior agent committed full implementations for all Phase 4 files. Added missing
+    TestPhaseJSONOmitEmpty and TestSectionJSONOmitEmpty tests; all other tests already existed. The
+    full task.go implementation (not stubs) was already present and correct per spec — all tests pass.
+  - Next task (Implement core types): implementation already exists and is correct; just verify tests
+    pass and mark completed.
+  ```
+
+- [completed] Implement core types (task.go)
+
+  ```notes
+  - Create `internal/task/task.go`
+  - Phase struct: `ID string "json:\"id\""`, `Name string "json:\"name,omitempty\""`, `Description string "json:\"description,omitempty\""`
+  - Section struct: `ID string "json:\"id\""`, `PhaseID string "json:\"phaseId\""`, `Name string "json:\"name,omitempty\""`, `Description string "json:\"description,omitempty\""`
+  - Task struct: `ID`, `Subject`, `Status` (TaskStatus), `PhaseID` (omitempty), `SectionID` (omitempty), `Notes` (omitempty), `LastUpdated` (time.Time) — JSON field names are camelCase
+  - TaskStatus type: `type TaskStatus string` with three constants
+  - TaskList struct: `Name` (omitempty), `Description` (omitempty), `Phases []Phase` (omitempty), `Sections []Section` (omitempty), `Tasks []Task`, `Version string`, `LastUpdated time.Time`
+  - Filter struct: `Status []TaskStatus`, `PhaseID string`, `SectionID string`, `Limit int` — used by Storage.List, not serialized to JSON
+  - generateID(): use `crypto/rand.Read(4 bytes)` → `hex.EncodeToString` → 8-char lowercase hex string
+  - All tests should pass
+  - Implementation was already present from prior overzealous agent; verified all tests pass against spec.
+  ```
+
+### Storage Core
+
+- [completed] Write tests for storage core (json_storage.go)
+
+  ```notes
+  - Test in `internal/task/json_storage_test.go`
+  - Use `t.TempDir()` for isolated `tasks.json` file in each test
+  - Test Load — non-existent file: returns empty `TaskList` with `Version: "1.0"` and empty `Tasks` slice (not an error)
+  - Test Load — existing file: write a JSON file manually, verify `Load()` deserializes all fields correctly (name, description, phases, sections, tasks, version, lastUpdated)
+  - Test Save: sets `TaskList.LastUpdated` to current time before writing; file is indented JSON (`json.MarshalIndent`); round-trips with `Load()`
+  - Test Save: file written with 0644 permissions
+  - Add Storage interface in `internal/task/storage.go` and JSONStorage struct stub in `internal/task/json_storage.go` for compilation
+  - JSONStorage stub: `Load()` returns `&TaskList{}` (not nil); all other methods return errors
+  - All tests should fail as expected (stubs are no-ops); no panics
+  - NOTE: Prior overzealous agent already wrote full implementation in json_storage.go and all test cases
+    for CRUD, list/filter in json_storage_test.go. Added missing test coverage: expanded
+    TestLoadExistingFile to verify all fields (description, phases, sections, version, lastUpdated),
+    and added TestSaveFilePermissions (0644). Full implementation was already present and correct.
+    All tests pass.
+  ```
+
+- [completed] Implement storage core (storage.go + json_storage.go)
+
+  ```notes
+  - Create `internal/task/storage.go` with Storage interface:
+    - `Load() (*TaskList, error)`
+    - `Save(list *TaskList) error`
+    - `Get(id string) (*Task, error)`
+    - `List(filter Filter) ([]Task, error)`
+    - `Create(task *Task) error`
+    - `Update(task *Task) error`
+    - `Delete(id string) error`
+  - Create `internal/task/json_storage.go` with JSONStorage struct:
+    - Fields: `mu sync.RWMutex`, `path string`
+    - Constructor: `NewJSONStorage(path string) *JSONStorage`
+  - Load: acquire read lock; read file; if `os.IsNotExist`, return `&TaskList{Version: "1.0", Tasks: []Task{}}` (not an error); unmarshal JSON
+  - Save: acquire write lock; set `list.LastUpdated = time.Now()`; `json.MarshalIndent(list, "", "  ")`; write to file with 0644 permissions
+  - Stub remaining methods (Get/List/Create/Update/Delete return errors) to satisfy the interface
+  - All tests should pass
+  - NOTE: Prior overzealous agent already implemented everything in storage.go and json_storage.go
+    including full CRUD and List. Verified all tests pass, marked completed.
+  ```
+
+### Storage Create, Get, Update, Delete
+
+- [completed] Write tests for storage create, get, update, delete (json_storage.go)
+
+  ```notes
+  - Continue in `internal/task/json_storage_test.go`
+  - Use `t.TempDir()` for isolated `tasks.json` file in each test
+  - Test Create: auto-sets `task.LastUpdated` to current time; task appears in subsequent `Load()`
+  - Test Create — duplicate ID: returns an error (does not overwrite)
+  - Test Get — found: returns correct task by ID
+  - Test Get — not found: returns an error
+  - Test Update — found: modifies fields; sets `LastUpdated` to current time; preserves unmodified fields
+  - Test Update — not found: returns an error
+  - Test Delete — found: removes task from list; subsequent `Get()` returns not found
+  - Test Delete — not found: returns an error
+  - Stubs from previous section already exist; all tests should fail as expected (stubs return errors); no panics
+  - NOTE: Overzealous prior agent already wrote all tests (TestCreate, TestCreateDuplicateID, TestGet,
+    TestGetNotFound, TestUpdate, TestUpdateNotFound, TestDelete, TestDeleteNotFound) and the full
+    implementation. All tests pass. Same pattern as previous tasks.
+  ```
+
+- [completed] Implement storage create, get, update, delete (json_storage.go)
+
+  ```notes
+  - Add to `internal/task/json_storage.go`
+  - Create: call Load; scan for duplicate ID (return error if found); set `task.LastUpdated = time.Now()`; append to `list.Tasks`; call Save
+  - Get: call Load; linear scan by ID; return error `"task not found: <id>"` if not found
+  - Update: call Load; find task by `task.ID`; replace in slice; set `task.LastUpdated = time.Now()`; call Save; error if not found
+  - Delete: call Load; find by ID; remove from slice; call Save; error if not found
+  - Note: Create/Update/Delete call Load then Save — no transaction; acceptable per spec (no multi-agent coordination required)
+  - Stub `List` (returns error) to satisfy the interface; implemented in subsequent task
+  - All tests should pass
+  - NOTE: Overzealous prior agent already wrote the full implementation. All tests pass. Verified and marked completed.
+  ```
+
+### Storage List & Filter
+
+- [completed] Write tests for storage list and filter (json_storage.go)
+
+  ```notes
+  - Continue in `internal/task/json_storage_test.go`
+  - Use `t.TempDir()` for isolated `tasks.json` file in each test
+  - Test List — no filter: returns all tasks
+  - Test List — status filter: single status returns only matching tasks
+  - Test List — status filter: multiple statuses (OR within the status list)
+  - Test List — PhaseID filter: only tasks matching the phase
+  - Test List — SectionID filter: only tasks matching the section
+  - Test List — combined filters: status + PhaseID (AND-combined)
+  - Test List — Limit: `Limit=0` means no limit; `Limit=N` returns at most N tasks
+  - Stub from previous section already exists (returns error); all tests should fail as expected; no panics
+  - Prior agent had already written tests for single status, PhaseID, SectionID, Limit, and NoLimit.
+    Added the three missing cases: TestListNoFilter, TestListFilterByMultipleStatuses, TestListFilterCombined.
+  - Full List implementation was already present; all tests pass.
+  ```
+
+- [completed] Implement storage list and filter (json_storage.go)
+
+  ```notes
+  - Add to `internal/task/json_storage.go`
+  - List: call Load; iterate tasks; apply filters (AND-combined): status matches any in `filter.Status` (OR within the status list); PhaseID exact match; SectionID exact match; empty filter fields are ignored; apply Limit after filtering (0 = no limit)
+  - All tests should pass
+  - Prior overzealous agent had already written the full List implementation. Verified all tests pass and marked completed.
+  ```
+
+### Single-Task Formatters
+
+- [completed] Write tests for single-task formatters (format.go)
+
+  ```notes
+  - Test in `internal/task/format_test.go`
+  - Use fixed `time.Time` values for deterministic output (e.g. `time.Date(2026, 3, 10, 14, 22, 0, 0, time.UTC)`)
+  - Create a helper TaskList fixture with phases and sections for name resolution tests
+
+  **FormatTaskMarkdown:**
+  - Test H1 heading is the task subject
+  - Test status is always shown: `**Status:** <status>`
+  - Test lastUpdated is always shown: `**Updated:** <ISO8601>`
+  - Test phase line: when phaseId is set and phase has a name, render `**Phase:** <name>`; when no name in phases list, render `**Phase:** <hex-id>`; when phaseId is empty, omit line entirely
+  - Test section line: same name-resolution rules as phase; omit when sectionId is empty
+  - Test notes non-empty: rendered as-is below field list, separated by blank line
+  - Test notes empty: render `**Notes:** (none)`
+
+  **FormatTaskJSON:**
+  - Test outputs single task object (not wrapped in `{"tasks": [...]}` envelope)
+  - Test all fields present including omitempty fields when populated
+  - Test valid JSON via `json.Unmarshal` round-trip
+
+  - Add function stubs `FormatTaskMarkdown` and `FormatTaskJSON` in `internal/task/format.go` returning zero values for compilation
+  - All tests should fail as expected (stubs return empty string/nil)
+  - NOTE: Overzealous prior agent already wrote tests for all formatters (single-task, list, export)
+    and the full format.go implementation. Verified all tests match spec requirements and pass.
+    Tests in `internal/task/format_test.go`: TestFormatTaskMarkdown (4 subtests covering all spec
+    cases), TestFormatTaskJSON (valid JSON + no envelope). All tests pass.
+  ```
+
+- [completed] Implement single-task formatters (format.go)
+
+  ```notes
+  - Create `internal/task/format.go`
+  - Function signatures:
+    - `FormatTaskMarkdown(task *Task, list *TaskList) string`
+    - `FormatTaskJSON(task *Task) (string, error)`
+
+  **FormatTaskMarkdown:**
+  - H1 = subject; always show `**Status:**` and `**Updated:**` (ISO8601)
+  - Phase/section: look up name in `list.Phases`/`list.Sections` by ID; use name if found, hex ID fallback; omit line if phaseId/sectionId empty
+  - Notes: if non-empty, blank line + notes content; if empty, `**Notes:** (none)`
+
+  **FormatTaskJSON:**
+  - `json.MarshalIndent(task, "", "  ")` — single object, no envelope
+
+  - All tests should pass
+  - NOTE: Full implementation already exists in `internal/task/format.go` from overzealous prior agent,
+    including FormatTaskMarkdown, FormatTaskJSON, FormatListMarkdown, FormatListJSON,
+    FormatExportMarkdown, and shared helpers. All tests pass. Verified all tests pass; marked completed.
+  ```
+
+### List Grouped Formatter
+
+- [completed] Write tests for list grouped formatter (format.go)
+
+  ```notes
+  - Continue in `internal/task/format_test.go`
+
+  **FormatListMarkdown (grouped mode):**
+  - Test grouped output: phase H2 headings, section H3 headings, task bullets
+  - Test bullet format: `- \`<id>\` [<status>] <subject>`
+  - Test notes rendering: non-empty notes → blank line after bullet, then fenced code block with `notes` info string, indented 2 spaces (opening fence, content lines, closing fence)
+  - Test tasks without notes render as bare bullets (no extra lines)
+  - Test phases/sections with zero matching tasks are omitted
+  - Test phase name resolution: name if available, hex ID fallback
+  - Test section name resolution: same rules
+  - Test tasks with no phase collected under `## (none)`
+  - Test tasks with no section appear directly under phase heading (no H3)
+  - Test NO project name/description H1 in list output (only in export)
+  - Test ordering: tasks ordered by phase position (order in `phases` array), then section position (order in `sections` array), then task ID
+
+  - Add stubs `FormatListMarkdown` and `FormatListJSON` to `internal/task/format.go` for compilation (both return empty string/nil)
+  - All tests should fail as expected
+  - NOTE: Overzealous prior agent already wrote TestFormatListMarkdown (2 subtests), TestFormatListMarkdownFlat, TestFormatListJSON, TestFormatExportMarkdown, and full implementations. Added 6 missing subtests to TestFormatListMarkdown: phase name hex fallback, section name hex fallback, tasks with no phase under (none), tasks without section directly under phase heading, tasks without notes as bare bullets, and ordering by phase/section position. All tests pass.
+  ```
+
+- [completed] Implement list grouped formatter (format.go)
+
+  ```notes
+  - Add to `internal/task/format.go`
+  - Function signature: `FormatListMarkdown(tasks []Task, list *TaskList, flat bool) string`
+
+  **Shared grouping helper (e.g. `renderGrouped`):**
+  - Group tasks by phaseId then sectionId
+  - Order phases by position in `list.Phases` array; orphan phases (tasks referencing phaseIds not in list) appended at end
+  - Order sections by position in `list.Sections` array within each phase
+  - Tasks with no phase → group key `""` → heading `## (none)`
+  - Tasks with no section → appear directly under phase heading, no H3
+  - Phase heading: `## {name}` if name exists, else `## {id}`
+  - Section heading: `### {name}` if name exists, else `### {id}`
+  - Task bullet: `` - `{id}` [{status}] {subject} ``
+  - Notes rendering: blank line after bullet, then fenced block with `notes` info string indented 2 spaces (keeps code block inside list item)
+  - `includeDescriptions bool` parameter: when false (list), skip phase/section description paragraphs; when true (export), render them
+
+  **FormatListMarkdown:**
+  - When flat=true: return `""` (stub; implemented in next section)
+  - When flat=false: call shared grouping helper with includeDescriptions=false (no project H1, no phase/section descriptions)
+
+  - All tests should pass
+  - NOTE: Implementation was already present from overzealous prior agent in `internal/task/format.go`.
+    Full `renderGrouped` helper, `renderFlatList`, `FormatListMarkdown`, `FormatListJSON`,
+    `FormatExportMarkdown` all implemented and passing all tests. Verified and marked completed.
+  ```
+
+### List Flat and JSON Formatters
+
+- [completed] Write tests for list flat and JSON formatters (format.go)
+
+  ```notes
+  - Continue in `internal/task/format_test.go`
+
+  **FormatListMarkdown flat mode (`--flat`):**
+  - Test suppresses phase and section headings
+  - Test omits notes
+  - Test output is flat bullet list: `- \`<id>\` [<status>] <subject>`
+
+  **FormatListJSON:**
+  - Test `{"tasks": [...]}` envelope wrapping task objects
+  - Test valid JSON round-trip
+
+  - Stubs already exist from previous section; all tests should fail as expected
+  - NOTE: Overzealous prior agent already wrote both TestFormatListMarkdownFlat and
+    TestFormatListJSON tests, and the full implementations. All spec requirements are
+    covered. All tests pass.
+  ```
+
+- [completed] Implement list flat and JSON formatters (format.go)
+
+  ```notes
+  - Add to `internal/task/format.go`
+  - Function signature: `FormatListJSON(tasks []Task) (string, error)`
+
+  **FormatListMarkdown flat path:**
+  - When flat=true: iterate tasks, emit bare bullets only (no headings, no notes)
+  - Replace the `""` stub from the previous section
+
+  **FormatListJSON:**
+  - Wrap tasks in `{"tasks": [...]}` envelope; `json.MarshalIndent`
+
+  - All tests should pass
+  - NOTE: Overzealous prior agent already wrote full implementations of `renderFlatList` and
+    `FormatListJSON` in `internal/task/format.go`. All tests pass. Verified and marked completed.
+  ```
+
+### Export Formatter
+
+- [completed] Write tests for export formatter (format.go)
+
+  ```notes
+  - Continue in `internal/task/format_test.go`
+
+  **FormatExportMarkdown:**
+  - Test project name renders as `# {name}` when set
+  - Test project description renders as paragraph after H1 when both name and description set
+  - Test no H1 when name is not set
+  - Test description skipped when name is not set (even if description is set)
+  - Test phase descriptions render as paragraphs below phase headings
+  - Test section descriptions render as paragraphs below section headings
+  - Test no description paragraph when description is empty (no blank placeholder)
+  - Test same task bullet and notes format as list markdown (shared rendering logic)
+
+  - Add stub `FormatExportMarkdown` to `internal/task/format.go` for compilation
+  - All tests should fail as expected
+  - NOTE: Overzealous prior agent already wrote most tests and the full FormatExportMarkdown
+    implementation. Added two missing subtests: "section description renders below section heading"
+    (FAILS — renderGrouped does not render section descriptions when includePhaseDesc=true; the
+    implementation task must fix this) and "no description paragraph when description is empty"
+    (PASSES — implementation correctly skips empty phase descriptions and never adds placeholders).
+  ```
+
+- [completed] Implement export formatter (format.go)
+
+  ```notes
+  - Add to `internal/task/format.go`
+  - Function signature: `FormatExportMarkdown(tasks []Task, list *TaskList) string`
+
+  **FormatExportMarkdown:**
+  - If `list.Name` is set, render `# {name}` as first line
+  - If `list.Description` is set AND name is set, render as paragraph after H1 followed by blank line
+  - If name is not set: skip both (no H1, no description)
+  - Call shared grouping helper (from list grouped formatter) with includeDescriptions=true to render phase/section descriptions
+
+  - Fixed: added section description rendering in `renderGrouped` after `### {section heading}` line
+    when `includePhaseDesc && sec.Description != ""`. The prior overzealous agent had only implemented
+    phase description rendering. One-line fix in `renderGrouped` in `format.go`.
+  - All tests pass.
+  ```
+
+### Dispatch
+
+- [completed] Write tests for dispatch (cmd.go)
+
+  ```notes
+  - Test in `internal/task/cmd_test.go`
+  - Define a `mockStorage` struct implementing the `Storage` interface for test isolation (no file I/O)
+  - mockStorage: in-memory `TaskList` with configurable phases/sections/tasks; records calls for assertion
+  - Function under test: `HandleTask(args []string, w io.Writer, storage Storage) int` — returns exit code
+  - Capture stdout via the `w io.Writer` parameter; capture stderr separately where needed
+
+  **Dispatch:**
+  - Test unknown subcommand: prints error to stderr, returns 1
+  - Test no subcommand: prints task usage to stderr, returns 1
+  - Test `--help`/`-h`: prints task usage to stderr, returns 0
+  - Test routes to correct handler for list, get, create, update, delete, export
+
+  **multiFlag type:**
+  - Test `String()` returns comma-joined values
+  - Test `Set()` appends to the slice (supports repeatable invocation)
+
+  - Add `HandleTask` stub returning 1 and `multiFlag` type stub in `internal/task/cmd.go` for compilation
+  - All tests should fail as expected (stub returns 1); no panics
+  - NOTE: Overzealous prior agent had already written the mockStorage, multiFlag tests, dispatch tests
+    (unknown/no-args), and full subcommand tests for list/get/create/update/export + full cmd.go
+    implementation. Added missing tests: TestHandleTaskHelp (--help/-h returns 0, FAILS — no
+    implementation), TestDeleteByID/TestDeleteCmdNotFound/TestDeleteMissingID (FAIL/PASS/PASS — stub
+    returns 1). Added deleteCmd stub and "delete" case to switch in cmd.go for compilation.
+  - Next task (Implement dispatch): must add --help/-h handling to HandleTask and implement deleteCmd
+  ```
+
+- [completed] Implement dispatch (cmd.go)
+
+  ```notes
+  - Create `internal/task/cmd.go`
+  - `HandleTask(args []string, w io.Writer, storage Storage) int` — main entry point
+  - `multiFlag` type: `type multiFlag []string` implementing `flag.Value`:
+    - `String()`: `strings.Join(f, ",")`
+    - `Set(value string)`: append to slice
+
+  **Dispatch logic:**
+  - No args: print task usage to stderr, return 1
+  - `--help`/`-help`/`-h` as first arg: print task usage to stderr, return 0
+  - Switch on `args[0]`: dispatch to list/get/create/update/delete/export handlers
+  - Unknown subcommand: print error + task usage to stderr, return 1
+
+  - Add stub handlers for list/get/create/update/delete/export (return 1) to satisfy the switch; implement in subsequent tasks
+  - All tests should pass
+  - Prior overzealous agent had implemented all handlers except deleteCmd (stub) and --help handling.
+  - Added --help/-help/-h case to HandleTask switch (returns 0).
+  - Implemented deleteCmd: extracts ID from args[0], returns 1 with usage if missing, calls storage.Delete(id), returns 1 with error if not found, returns 0.
+  - All tests pass.
+  ```
+
+### List Subcommand
+
+- [completed] Write tests for list handler (cmd.go)
+
+  ```notes
+  - Continue in `internal/task/cmd_test.go`
+
+  **list subcommand:**
+  - Test default format is markdown
+  - Test `--status=pending` filters to matching tasks
+  - Test `--status` is repeatable: `--status=pending --status=in_progress` passes both statuses
+  - Test `--phase=<hex-id>` passes PhaseID filter to storage
+  - Test `--section=<hex-id>` passes SectionID filter to storage
+  - Test `--limit=5` passes Limit filter to storage
+  - Test `--flat` passes flat=true to FormatListMarkdown
+  - Test `--format=json` outputs JSON envelope
+  - Test `--flat` with `--format=json`: flat flag is ignored, output is JSON envelope (--flat only applies to markdown)
+  - Test invalid `--status` value: returns 1 with error message
+
+  - Stub for list handler already exists (returns 1); all tests should fail as expected
+  - NOTE: Overzealous prior agent had already written most list tests and the full listCmd implementation.
+    Added 3 missing tests: TestListSectionFilter (--section filter), TestListFlatWithJSON (--flat ignored
+    with --format=json), TestListInvalidStatus (invalid status returns 1). All tests pass.
+  - Next task (Implement list handler): implementation already exists and is correct; just verify tests
+    pass and mark completed.
+  ```
+
+- [completed] Implement list handler (cmd.go)
+
+  ```notes
+  - Add to `internal/task/cmd.go`
+
+  **list handler:**
+  - `flag.NewFlagSet("lorah task list", flag.ContinueOnError)`
+  - Flags: `--status` (multiFlag), `--phase` (string), `--section` (string), `--limit` (int, default 0), `--flat` (bool), `--format` (string, default `"markdown"`)
+  - Validate each status value against TaskStatus constants; return 1 on invalid
+  - Build Filter; call `storage.List(filter)`
+  - Call `storage.Load()` to get full TaskList for name resolution in markdown output
+  - Format: `--format=json` → FormatListJSON; default → FormatListMarkdown(tasks, list, flat)
+  - Write to `w`; return 0
+
+  - All tests should pass
+  - NOTE: Full implementation already existed from overzealous prior agent in cmd.go. Verified all tests pass; marked completed.
+  ```
+
+### Get Subcommand
+
+- [completed] Write tests for get handler (cmd.go)
+
+  ```notes
+  - Continue in `internal/task/cmd_test.go`
+
+  **get subcommand:**
+  - Test retrieves task by ID (first positional arg)
+  - Test default format is markdown; output includes subject as H1
+  - Test `--format=json` outputs single task JSON object (no envelope)
+  - Test task not found: returns 1 with error message
+  - Test no ID argument: returns 1 with usage
+
+  - Stub for get handler already exists (returns 1); all tests should fail as expected
+  - NOTE: Overzealous prior agent had already written all 4 get tests (TestGetByID,
+    TestGetCmdNotFound, TestGetMissingID, TestGetJSONFormat) and the full getCmd
+    implementation. Strengthened TestGetByID to verify subject appears as `# Subject`
+    H1 (was only checking `strings.Contains(out, "Test get")`). All tests pass.
+  - Next task (Implement get handler): implementation already exists and is correct;
+    just verify tests pass and mark completed.
+  ```
+
+- [completed] Implement get handler (cmd.go)
+
+  ```notes
+  - Add to `internal/task/cmd.go`
+
+  **get handler:**
+  - `flag.NewFlagSet("lorah task get", flag.ContinueOnError)`; extract ID from `fs.Arg(0)`
+  - Return 1 with usage if no ID provided
+  - Call `storage.Get(id)` — return 1 with error message if not found
+  - Call `storage.Load()` for name resolution
+  - Format: `--format=json` → FormatTaskJSON; default → FormatTaskMarkdown(task, list)
+  - Write to `w`; return 0
+
+  - All tests should pass
+  - NOTE: Implementation was already present from the overzealous prior agent in cmd.go. Verified all
+    tests pass; marked completed.
+  ```
+
+### Create Subcommand
+
+- [completed] Write tests for create handler (cmd.go)
+
+  ```notes
+  - Continue in `internal/task/cmd_test.go`
+
+  **create subcommand — basic creation:**
+  - Test `--subject` is required: returns 1 if missing
+  - Test creates task with auto-generated ID; prints `task <hex-id>` to stdout
+  - Test default status is `pending`
+  - Test `--status=in_progress` sets status on created task
+  - Test invalid `--status` value: returns 1 with error message
+  - Test `--phase=<hex-id>` assigns task to existing phase (no new phase created, no "phase" line printed)
+  - Test `--section=<hex-id>` assigns task to existing section (no new section created)
+  - Test `--section=<hex-id>` without phase context (no `--phase` or `--phase-name`): returns 1 with error
+
+  - Stub for create handler already exists (returns 1); all tests should fail as expected
+  - NOTE: Most create tests already existed from the overzealous prior agent (TestCreateRequiresSubject,
+    TestCreateBasic, TestCreateWithExistingPhase, TestCreateInvalidStatus). Added 3 missing tests:
+    TestCreateWithStatus (PASSES — implementation already validates status), TestCreateWithExistingSection
+    (PASSES — implementation sets sectionID correctly), TestCreateSectionWithoutPhaseContext (FAILS —
+    implementation doesn't validate that --section requires a phase context per spec).
+  - Next task (Implement create handler): must add validation that --section without phase context returns 1.
+  ```
+
+- [completed] Implement create handler (cmd.go)
+
+  ```notes
+  - Add to `internal/task/cmd.go`
+
+  **create handler (basic creation):**
+  - `flag.NewFlagSet("lorah task create", flag.ContinueOnError)`
+  - Flags: `--subject` (string), `--status` (string, default `"pending"`), `--phase`, `--phase-name`, `--phase-description`, `--section`, `--section-name`, `--section-description`, `--project-name`, `--project-description`
+  - Validate: `--subject` non-empty (return 1); `--status` valid TaskStatus (return 1)
+  - `--phase` provided: set phaseId directly
+  - `--section` provided: validate phase context exists (`--phase` or `--phase-name`), return 1 with error if missing; set sectionId directly
+  - Build Task with `generateID()`, subject, status (as TaskStatus), phaseId, sectionId
+  - Call `storage.Create(&task)`
+  - Print `task <id>` to stdout; return 0
+  - Auto-generation flags (`--phase-name`, `--phase-description`, `--section-name`, `--section-description`, `--project-name`, `--project-description`) parsed but not yet handled (implemented in next section)
+
+  - All tests should pass
+  - Prior overzealous agent had already written most of the implementation (auto-generation included).
+    Only missing validation: `--section` without phase context (`--phase` or `--phase-name`) must return 1.
+    Added guard before `sectionID = *section` in createCmd. All tests pass.
+  ```
+
+### Create Auto-Generation
+
+- [completed] Write tests for create auto-generation (cmd.go)
+
+  ```notes
+  - Continue in `internal/task/cmd_test.go`
+
+  **create subcommand — auto-generation:**
+  - Test `--phase-name="Phase 1"` without `--phase`: auto-generates new phase ID, creates Phase entry, prints `phase <hex-id>` before `task <hex-id>`
+  - Test `--phase-description="..."`: sets description on auto-generated phase
+  - Test `--section-name="1.1 Foo"` without `--section`: auto-generates section ID, creates Section entry with correct PhaseID, prints `section <hex-id>` between phase and task lines
+  - Test `--section-description="..."`: sets description on auto-generated section
+  - Test `--project-name` sets TaskList.Name
+  - Test `--project-description` sets TaskList.Description
+  - Test output ordering: `phase <id>` before `section <id>` before `task <id>` (only newly created entities)
+  - Test `--section-name` without phase context (no `--phase` or `--phase-name`): returns 1 with error
+
+  - Several tests already existed from prior iterations (TestCreateWithPhaseName, TestCreateWithPhaseAndSectionName, TestCreateWithProjectNameAndDescription).
+  - Added 5 new tests: TestCreatePhaseDescription, TestCreateSectionDescription, TestCreateSectionPhaseIDAssigned, TestCreateOutputOrdering, TestCreateSectionNameWithoutPhaseContext.
+  - TestCreateSectionNameWithoutPhaseContext FAILS as expected — implementation guards `--section` without phase context but not `--section-name` without phase context.
+  - All other new tests PASS against the existing implementation.
+  ```
+
+- [completed] Implement create auto-generation (cmd.go)
+
+  ```notes
+  - Add to the create handler in `internal/task/cmd.go`
+
+  **Phase auto-generation:**
+  - `--phase-name` or `--phase-description` without `--phase`: auto-generate phase ID, create Phase entry, append to list.Phases, record as "newly created" → print `phase <id>`
+  - `--phase` provided with `--phase-name` or `--phase-description`: upsert on the existing phase in list.Phases
+
+  **Section auto-generation:**
+  - `--section-name` or `--section-description` without `--section`: auto-generate section ID, create Section with PhaseID, append to list.Sections, record as "newly created" → print `section <id>`
+  - `--section-name` without any phase context: return 1 with error
+
+  **Project metadata:**
+  - Apply `--project-name`/`--project-description` to list
+
+  **Storage:**
+  - Call `storage.Save(list)` to persist phase/section/project metadata before `storage.Create(&task)`
+  - Print: `phase <id>` (if new), `section <id>` (if new), `task <id>` (always)
+
+  - Added guard in `else if *sectionName != "" || *sectionDesc != ""` branch: checks `phaseID == ""`
+    and returns 1 with error "—section-name requires a phase context (--phase or --phase-name)".
+  - All other auto-generation logic was already implemented by prior overzealous agent.
+  - All tests pass.
+  ```
+
+### Update Basic Fields
+
+- [completed] Write tests for update basic fields (cmd.go)
+
+  ```notes
+  - Continue in `internal/task/cmd_test.go`
+
+  **update subcommand — basic fields:**
+  - Test partial update via `fs.Visit`: only explicitly provided flags modify fields (omitted flags leave fields unchanged)
+  - Test `--status=completed` updates status
+  - Test `--subject="new"` updates subject; `--subject=""` clears subject (not treated as "not provided")
+  - Test `--notes="..."` replaces notes field
+  - Test task not found: returns 1 with error message
+  - Test no ID argument: returns 1 with usage
+  - Test invalid `--status` value: returns 1 with error message
+
+  - Stub for update handler already exists (returns 1); all tests should fail as expected
+  - NOTE: Overzealous prior agent had already written most update tests (TestUpdateStatus,
+    TestUpdateNotes, TestUpdateCmdNotFound, TestUpdateMissingID, TestUpdatePartialPreservesFields,
+    TestUpdateInvalidStatus, TestUpdateSetsLastUpdated) and the full updateCmd implementation.
+    Added 2 missing tests: TestUpdateSubject (--subject updates subject) and TestUpdateSubjectClear
+    (--subject="" clears subject, not treated as "not provided"). All tests pass.
+  - Next task (Implement update basic fields): implementation already exists and is correct;
+    just verify tests pass and mark completed.
+  ```
+
+- [completed] Implement update basic fields (cmd.go)
+
+  ```notes
+  - Add to `internal/task/cmd.go`
+
+  **update handler (basic fields):**
+  - `flag.NewFlagSet("lorah task update", flag.ContinueOnError)`
+  - Extract ID from `fs.Arg(0)`; return 1 with usage if missing
+  - Flags: `--status`, `--subject`, `--phase`, `--phase-name`, `--phase-description`, `--section`, `--section-name`, `--section-description`, `--notes`, `--project-name`, `--project-description`
+  - Use `fs.Visit` after `fs.Parse` to build `provided map[string]bool` — only update fields where `provided["flag-name"]` is true
+  - Load task via `storage.Get(id)` — return 1 if not found
+  - Apply only provided basic fields to task: status (validate), subject, phaseId, sectionId, notes
+  - Call `storage.Update(&task)`; return 0
+  - Metadata flags (`--phase-name`, `--phase-description`, `--section-name`, `--section-description`, `--project-name`, `--project-description`) parsed but not yet handled (implemented in next section)
+
+  - All tests should pass
+  - NOTE: Prior overzealous agent already wrote the full updateCmd implementation including metadata
+    handling (phase-name, phase-description, section-name, section-description, project-name,
+    project-description). All tests pass. Verified and marked completed.
+  - NOTE for next task (Write tests for update metadata): implementation already exists and handles
+    all metadata mutations; tests must match existing behavior. See updateCmd in cmd.go lines 306-430.
+  ```
+
+### Update Metadata
+
+- [completed] Write tests for update metadata (cmd.go)
+
+  ```notes
+  - Continue in `internal/task/cmd_test.go`
+
+  **update subcommand — metadata:**
+  - Test `--phase=<hex-id>` reassigns phase on task
+  - Test `--phase-name="..."` upserts name on phase referenced by `--phase` (requires `--phase`)
+  - Test `--phase-description="..."` upserts description on phase (requires `--phase`)
+  - Test `--section=<hex-id>` reassigns section (requires `--phase`)
+  - Test `--section-name="..."` upserts name on section referenced by `--section` (requires `--section`)
+  - Test `--section-description="..."` upserts description on section (requires `--section`)
+  - Test `--project-name` / `--project-description` set TaskList metadata
+  - Test `--phase-name` without `--phase`: returns 1 with error
+  - Test `--phase-description` without `--phase`: returns 1 with error
+  - Test `--section` without `--phase`: returns 1 with error
+  - Test `--section-name` without `--section`: returns 1 with error
+  - Test `--section-description` without `--section`: returns 1 with error
+
+  - Stubs from previous section already exist; all tests should fail as expected
+  - Added 12 tests: TestUpdatePhaseReassigns, TestUpdatePhaseNameUpserts, TestUpdatePhaseDescriptionUpserts,
+    TestUpdateSectionReassigns, TestUpdateSectionNameUpserts, TestUpdateSectionDescriptionUpserts,
+    TestUpdateProjectMetadata (all PASS), and TestUpdatePhaseNameRequiresPhase,
+    TestUpdatePhaseDescriptionRequiresPhase, TestUpdateSectionRequiresPhase,
+    TestUpdateSectionNameRequiresSection, TestUpdateSectionDescriptionRequiresSection (all FAIL — impl
+    silently skips instead of returning 1).
+  - Next task (Implement update metadata): must add validation guards before the metadata upsert logic
+    in updateCmd so that --phase-name/--phase-description without --phase, --section without --phase,
+    and --section-name/--section-description without --section all return 1 with an error message.
+  ```
+
+- [completed] Implement update metadata (cmd.go)
+
+  ```notes
+  - Add to the update handler in `internal/task/cmd.go`
+
+  **Metadata handling:**
+  - Load TaskList via `storage.Load()` for metadata operations
+  - `--phase-name`/`--phase-description`: require `--phase` (return 1 if not provided); upsert on list.Phases entry matching the phase ID
+  - `--section`/`--section-name`/`--section-description`: require `--phase` (return 1 if not provided); `--section-name`/`--section-description` additionally require `--section`; upsert on list.Sections entry
+  - Apply project metadata (`--project-name`, `--project-description`) to list if provided
+  - Call `storage.Save(list)` after applying metadata changes
+
+  - All tests should pass
+  - Prior overzealous agent had already implemented the metadata upsert logic in updateCmd but was
+    silently skipping metadata operations when required dependent flags were missing instead of
+    returning 1. Added 5 validation guards (phase-name/phase-description require --phase;
+    section requires --phase; section-name/section-description require --section) placed before
+    any storage operations to avoid partial writes. All 5 failing tests now pass.
+  ```
+
+### Delete Subcommand
+
+- [completed] Write tests for delete handler (cmd.go)
+
+  ```notes
+  - Continue in `internal/task/cmd_test.go`
+
+  **delete subcommand:**
+  - Test deletes task by ID; returns 0 with no output
+  - Test task not found: returns 1 with error message
+  - Test no ID argument: returns 1 with usage
+
+  - Stub for delete handler already exists (returns 1); all tests should fail as expected
+  - NOTE: Overzealous prior agent already wrote all 3 delete tests (TestDeleteByID,
+    TestDeleteCmdNotFound, TestDeleteMissingID) and the full deleteCmd implementation.
+    All tests pass. Next task (Implement delete handler): implementation already exists
+    and is correct; just verify tests pass and mark completed.
+  ```
+
+- [completed] Implement delete handler (cmd.go)
+
+  ```notes
+  - Add to `internal/task/cmd.go`
+
+  **delete handler:**
+  - `flag.NewFlagSet("lorah task delete", flag.ContinueOnError)`
+  - Extract ID from `fs.Arg(0)`; return 1 with usage if missing
+  - Call `storage.Delete(id)` — return 1 with error message if not found
+  - Return 0
+
+  - All tests should pass
+  - NOTE: Prior overzealous agent already wrote full deleteCmd implementation in cmd.go. Verified
+    all 5 delete tests pass (TestDeleteByID, TestDeleteCmdNotFound, TestDeleteMissingID,
+    TestDelete, TestDeleteNotFound). Marked completed.
+  ```
+
+### Export Subcommand
+
+- [completed] Write tests for export handler (cmd.go)
+
+  ```notes
+  - Continue in `internal/task/cmd_test.go`
+
+  **export subcommand:**
+  - Test default: outputs export markdown to `w` (stdout)
+  - Test `--output=<file>`: writes to specified file path instead of `w`
+  - Test `--status=pending` filter: only matching tasks included
+  - Test `--status` is repeatable
+  - Test output is export markdown format (includes project H1 if name is set, phase/section descriptions)
+
+  - Stub for export handler already exists (returns 1); all tests should fail as expected
+  - NOTE: Overzealous prior agent had already written TestExportBasic, TestExportStatusFilter,
+    TestExportToFile and the full exportCmd implementation. Added 2 missing tests:
+    TestExportStatusRepeatable (--status repeatable with OR semantics) and
+    TestExportPhaseAndSectionDescriptions (verifies project H1, phase descriptions, section
+    descriptions in export output). All tests pass.
+  - Next task (Implement export handler): implementation already exists and is correct;
+    just verify tests pass and mark completed.
+  ```
+
+- [completed] Implement export handler (cmd.go)
+
+  ```notes
+  - Add to `internal/task/cmd.go`
+
+  **export handler:**
+  - `flag.NewFlagSet("lorah task export", flag.ContinueOnError)`
+  - Flags: `--output` (string), `--status` (multiFlag)
+  - Build Filter from status flags; call `storage.List(filter)` and `storage.Load()`
+  - Call `FormatExportMarkdown(tasks, list)`
+  - If `--output` provided: write to file; else: write to `w`
+  - Return 0
+
+  - All tests should pass
+  - NOTE: Prior overzealous agent already wrote the full exportCmd implementation in cmd.go.
+    Implementation correctly handles --status (repeatable with multiFlag), --output (file path),
+    FormatExportMarkdown, and stdout fallback. All 5 export tests pass. Verified and marked completed.
+  ```
+
+### Wire-Up
+
+- [completed] Wire up task command to main.go
+
+  ```notes
+  - Update `taskCmd` in `main.go`:
+    - Create `task.NewJSONStorage("tasks.json")` pointing to tasks.json in the working directory
+    - Call `task.HandleTask(args, os.Stdout, storage)` and propagate non-zero exit code
+    - Import `internal/task` package
+  - No new tests needed — existing routing tests in `main_test.go` cover the dispatch path
+  - Verify: `go build` succeeds; `lorah task --help` prints usage; `lorah task list` runs against empty state without error
+  - NOTE: Prior overzealous agent had already fully implemented the wire-up in main.go: taskCmd creates
+    NewJSONStorage("tasks.json") and calls HandleTask(args, os.Stdout, storage). All tests pass.
+    Verified and marked completed.
+  ```
diff --git a/internal/loop/claude.go b/internal/loop/claude.go
new file mode 100644
index 0000000..1649cfb
--- /dev/null
+++ b/internal/loop/claude.go
@@ -0,0 +1,42 @@
+package loop
+
+import (
+	"context"
+	"fmt"
+	"os"
+	"os/exec"
+)
+
+// execCommandContext is the exec.CommandContext function used by runClaude.
+// Overridden in tests to inject a fake "claude" subprocess.
+var execCommandContext = exec.CommandContext
+
+// runClaude executes a single Claude Code CLI session with the prompt file piped to stdin.
+func runClaude(ctx context.Context, promptFile string, flags []string) error {
+	file, err := os.Open(promptFile)
+	if err != nil {
+		return fmt.Errorf("opening prompt file: %w", err)
+	}
+	defer file.Close()
+
+	args := append([]string{"-p", "--output-format", "stream-json", "--verbose"}, flags...)
+	cmd := execCommandContext(ctx, "claude", args...)
+	cmd.Stdin = file
+	cmd.Stderr = os.Stderr
+
+	stdout, err := cmd.StdoutPipe()
+	if err != nil {
+		return fmt.Errorf("creating stdout pipe: %w", err)
+	}
+
+	if err := cmd.Start(); err != nil {
+		return fmt.Errorf("starting Claude Code CLI: %w", err)
+	}
+
+	printMessages(stdout)
+
+	if err := cmd.Wait(); err != nil {
+		return fmt.Errorf("Claude Code CLI exited with error: %w", err)
+	}
+	return nil
+}
diff --git a/internal/loop/claude_test.go b/internal/loop/claude_test.go
new file mode 100644
index 0000000..845b6f1
--- /dev/null
+++ b/internal/loop/claude_test.go
@@ -0,0 +1,154 @@
+package loop
+
+import (
+	"context"
+	"io"
+	"os"
+	"os/exec"
+	"strings"
+	"testing"
+)
+
+// TestHelperProcess is not a real test — it's a helper that acts as the fake
+// "claude" CLI process when invoked by tests using the TestHelperProcess pattern.
+func TestHelperProcess(t *testing.T) {
+	if os.Getenv("GO_TEST_HELPER_PROCESS") != "1" {
+		return
+	}
+
+	// Find args after the "--" separator (everything before is test framework args).
+	args := os.Args
+	for i, a := range args {
+		if a == "--" {
+			args = args[i+1:]
+			break
+		}
+	}
+
+	// Write the received args to a file if the test requested it.
+	if f := os.Getenv("GO_TEST_ARGS_FILE"); f != "" {
+		_ = os.WriteFile(f, []byte(strings.Join(args, "\n")), 0600)
+	}
+
+	// Write stdin content to a file if the test requested it.
+	if f := os.Getenv("GO_TEST_STDIN_FILE"); f != "" {
+		data, _ := io.ReadAll(os.Stdin)
+		_ = os.WriteFile(f, data, 0600)
+	} else {
+		_, _ = io.Copy(io.Discard, os.Stdin)
+	}
+
+	// Exit with the specified code (default 0).
+	if os.Getenv("GO_TEST_EXIT_CODE") == "1" {
+		os.Exit(1)
+	}
+	os.Exit(0)
+}
+
+// helperClaudeFunc returns an execCommandContext override that runs the test
+// binary itself as the "claude" subprocess via TestHelperProcess.
+func helperClaudeFunc(extraEnv ...string) func(context.Context, string, ...string) *exec.Cmd {
+	return func(ctx context.Context, _ string, arg ...string) *exec.Cmd {
+		cs := append([]string{"-test.run=TestHelperProcess", "--"}, arg...)
+		cmd := exec.CommandContext(ctx, os.Args[0], cs...)
+		env := append(os.Environ(), "GO_TEST_HELPER_PROCESS=1")
+		cmd.Env = append(env, extraEnv...)
+		return cmd
+	}
+}
+
+// TestRunClaude_CorrectArgs verifies that runClaude passes the expected args to claude:
+// -p, --output-format, stream-json, --verbose, followed by any passthrough flags.
+func TestRunClaude_CorrectArgs(t *testing.T) {
+	argsFile := t.TempDir() + "/args.txt"
+
+	old := execCommandContext
+	defer func() { execCommandContext = old }()
+	execCommandContext = helperClaudeFunc("GO_TEST_ARGS_FILE=" + argsFile)
+
+	promptFile := t.TempDir() + "/prompt.md"
+	if err := os.WriteFile(promptFile, []byte("test prompt"), 0600); err != nil {
+		t.Fatal(err)
+	}
+
+	captureOutput(func() {
+		_ = runClaude(context.Background(), promptFile, []string{"--extra-flag"})
+	})
+
+	argsData, err := os.ReadFile(argsFile)
+	if err != nil {
+		t.Fatalf("args file not written (runClaude never called execCommandContext): %v", err)
+	}
+	got := string(argsData)
+
+	for _, want := range []string{"-p", "--output-format", "stream-json", "--verbose", "--extra-flag"} {
+		if !strings.Contains(got, want) {
+			t.Errorf("expected arg %q in claude args, got: %q", want, got)
+		}
+	}
+}
+
+// TestRunClaude_PromptFilePipedToStdin verifies that the prompt file contents are
+// piped to the claude subprocess stdin.
+func TestRunClaude_PromptFilePipedToStdin(t *testing.T) {
+	stdinFile := t.TempDir() + "/stdin.txt"
+
+	old := execCommandContext
+	defer func() { execCommandContext = old }()
+	execCommandContext = helperClaudeFunc("GO_TEST_STDIN_FILE=" + stdinFile)
+
+	promptContent := "this is the prompt content"
+	promptFile := t.TempDir() + "/prompt.md"
+	if err := os.WriteFile(promptFile, []byte(promptContent), 0600); err != nil {
+		t.Fatal(err)
+	}
+
+	captureOutput(func() {
+		_ = runClaude(context.Background(), promptFile, nil)
+	})
+
+	stdinData, err := os.ReadFile(stdinFile)
+	if err != nil {
+		t.Fatalf("stdin file not written (runClaude never piped stdin): %v", err)
+	}
+	if string(stdinData) != promptContent {
+		t.Errorf("expected stdin %q, got %q", promptContent, string(stdinData))
+	}
+}
+
+// TestRunClaude_MissingPromptFile verifies that runClaude returns an error with the
+// "opening prompt file:" prefix when the prompt file does not exist.
+func TestRunClaude_MissingPromptFile(t *testing.T) {
+	old := execCommandContext
+	defer func() { execCommandContext = old }()
+	execCommandContext = helperClaudeFunc()
+
+	err := runClaude(context.Background(), "/nonexistent/path/to/prompt.md", nil)
+	if err == nil {
+		t.Fatal("expected error for missing prompt file, got nil")
+	}
+	if !strings.HasPrefix(err.Error(), "opening prompt file:") {
+		t.Errorf("expected error prefix %q, got: %q", "opening prompt file:", err.Error())
+	}
+}
+
+// TestRunClaude_SubprocessError verifies that a non-zero exit from claude returns
+// an error prefixed "Claude Code CLI exited with error:".
+func TestRunClaude_SubprocessError(t *testing.T) {
+	old := execCommandContext
+	defer func() { execCommandContext = old }()
+	execCommandContext = helperClaudeFunc("GO_TEST_EXIT_CODE=1")
+
+	promptFile := t.TempDir() + "/prompt.md"
+	if err := os.WriteFile(promptFile, []byte("prompt"), 0600); err != nil {
+		t.Fatal(err)
+	}
+
+	err := runClaude(context.Background(), promptFile, nil)
+	if err == nil {
+		t.Fatal("expected error for failing subprocess, got nil")
+	}
+	if !strings.HasPrefix(err.Error(), "Claude Code CLI exited with error:") {
+		t.Errorf("expected error prefix %q, got: %q", "Claude Code CLI exited with error:", err.Error())
+	}
+}
diff --git a/internal/loop/constants.go b/internal/loop/constants.go
new file mode 100644
index 0000000..3a3c859
--- /dev/null
+++ b/internal/loop/constants.go
@@ -0,0 +1,14 @@
+package loop
+
+import "time"
+
+const (
+	colorReset = "\033[0m"
+	colorGreen = "\033[32m"
+	colorBlue  = "\033[34m"
+	colorBold  = "\033[1m"
+	colorRed   = "\033[31m"
+
+	maxBufferSize = 1024 * 1024 // 1MB buffer for JSON parsing
+	retryDelay    = 5 * time.Second
+)
diff --git a/internal/loop/loop.go b/internal/loop/loop.go
new file mode 100644
index 0000000..0052da1
--- /dev/null
+++ b/internal/loop/loop.go
@@ -0,0 +1,72 @@
+package loop
+
+import (
+	"context"
+	"fmt"
+	"os"
+	"os/signal"
+	"sync/atomic"
+	"syscall"
+	"time"
+)
+
+// Run starts the infinite Claude Code CLI execution loop.
+// It handles signal interrupts and retries on error.
+// Run does not return under normal operation.
+func Run(promptFile string, claudeFlags []string) {
+	ctx, cancel := context.WithCancel(context.Background())
+
+	sigCh := make(chan os.Signal, 2)
+	signal.Notify(sigCh, os.Interrupt, syscall.SIGTERM)
+
+	var stopping atomic.Bool
+	go handleSignals(sigCh, &stopping, cancel, os.Exit)
+
+	run(ctx, promptFile, claudeFlags, runClaude, &stopping, retryDelay)
+	os.Exit(0)
+}
+
+// run is the testable core of Run.
+// It loops until stopping is set, then returns.
+func run(ctx context.Context, promptFile string, flags []string,
+	runFn func(context.Context, string, []string) error,
+	stopping *atomic.Bool, delay time.Duration) {
+
+	iteration := 0
+	for {
+		iteration++
+		printSection("Lorah", colorBlue, fmt.Sprintf("Starting loop %d...", iteration))
+
+		if err := runFn(ctx, promptFile, flags); err != nil {
+			fmt.Fprintf(os.Stderr, "%s⏺ %sError%s\n", colorRed, colorBold, colorReset)
+			fmt.Fprintf(os.Stderr, "%v\n\n", err)
+			fmt.Fprintf(os.Stderr, "Retrying in %v...\n\n", delay)
+			time.Sleep(delay)
+		} else {
+			printSection("Lorah", colorBlue, fmt.Sprintf("Loop %d completed successfully", iteration))
+		}
+
+		if stopping.Load() {
+			return
+		}
+	}
+}
+
+// handleSignals processes OS signals from sigCh.
+// First signal sets stopping. Second signal cancels ctx and calls exitFn(0).
+func handleSignals(sigCh <-chan os.Signal, stopping *atomic.Bool, cancel context.CancelFunc, exitFn func(int)) {
+	for range sigCh {
+		if !stopping.Swap(true) {
+			// First signal: stop after current iteration
+			fmt.Println()
+			printSection("Lorah", colorBlue, "Received interrupt, stopping after current loop...")
+		} else {
+			// Second signal: cancel context and exit immediately
+			fmt.Println()
+			printSection("Lorah", colorBlue, "Received second interrupt, shutting down...")
+			cancel()
+			exitFn(0)
+			return
+		}
+	}
+}
diff --git a/internal/loop/loop_test.go b/internal/loop/loop_test.go
new file mode 100644
index 0000000..4813238
--- /dev/null
+++ b/internal/loop/loop_test.go
@@ -0,0 +1,255 @@
+package loop
+
+import (
+	"context"
+	"errors"
+	"io"
+	"os"
+	"strings"
+	"sync/atomic"
+	"testing"
+	"time"
+)
+
+// captureOutput redirects os.Stdout and os.Stderr, runs fn, then restores them.
+func captureOutput(fn func()) (stdout, stderr string) {
+	oldStdout := os.Stdout
+	rOut, wOut, _ := os.Pipe()
+	os.Stdout = wOut
+
+	oldStderr := os.Stderr
+	rErr, wErr, _ := os.Pipe()
+	os.Stderr = wErr
+
+	fn()
+
+	wOut.Close()
+	wErr.Close()
+
+	outBytes, _ := io.ReadAll(rOut)
+	errBytes, _ := io.ReadAll(rErr)
+
+	os.Stdout = oldStdout
+	os.Stderr = oldStderr
+
+	return string(outBytes), string(errBytes)
+}
+
+// TestRun_IteratesUntilStopping verifies the loop calls runFn on each iteration
+// and exits when stopping is set after the iteration completes.
+func TestRun_IteratesUntilStopping(t *testing.T) {
+	ctx, cancel := context.WithCancel(context.Background())
+	defer cancel()
+
+	var stopping atomic.Bool
+	callCount := 0
+
+	runFn := func(_ context.Context, _ string, _ []string) error {
+		callCount++
+		if callCount >= 3 {
+			stopping.Store(true)
+		}
+		return nil
+	}
+
+	captureOutput(func() {
+		run(ctx, "test.md", nil, runFn, &stopping, 0)
+	})
+
+	if callCount != 3 {
+		t.Errorf("expected 3 iterations, got %d", callCount)
+	}
+}
+
+// TestRun_PrintsStartSection verifies "Starting loop 1..." appears in stdout on the first iteration.
+func TestRun_PrintsStartSection(t *testing.T) {
+	ctx, cancel := context.WithCancel(context.Background())
+	defer cancel()
+
+	var stopping atomic.Bool
+	stopping.Store(true) // exit after first iteration
+
+	runFn := func(_ context.Context, _ string, _ []string) error {
+		return nil
+	}
+
+	stdout, _ := captureOutput(func() {
+		run(ctx, "test.md", nil, runFn, &stopping, 0)
+	})
+
+	if !strings.Contains(stdout, "Starting loop 1...") {
+		t.Errorf("expected 'Starting loop 1...' in stdout, got: %q", stdout)
+	}
+}
+
+// TestRun_PrintsSuccessSection verifies "Loop 1 completed successfully" appears after the first successful iteration.
+func TestRun_PrintsSuccessSection(t *testing.T) {
+	ctx, cancel := context.WithCancel(context.Background())
+	defer cancel()
+
+	var stopping atomic.Bool
+	stopping.Store(true) // exit after first iteration
+
+	runFn := func(_ context.Context, _ string, _ []string) error {
+		return nil
+	}
+
+	stdout, _ := captureOutput(func() {
+		run(ctx, "test.md", nil, runFn, &stopping, 0)
+	})
+
+	if !strings.Contains(stdout, "Loop 1 completed successfully") {
+		t.Errorf("expected 'Loop 1 completed successfully' in stdout, got: %q", stdout)
+	}
+}
+
+// TestRun_ErrorHandling verifies that on runFn error, the error is printed to stderr
+// with a retry message, and the loop continues.
+func TestRun_ErrorHandling(t *testing.T) {
+	ctx, cancel := context.WithCancel(context.Background())
+	defer cancel()
+
+	var stopping atomic.Bool
+	callCount := 0
+
+	runFn := func(_ context.Context, _ string, _ []string) error {
+		callCount++
+		stopping.Store(true) // exit after this (error) iteration
+		return errors.New("some error occurred")
+	}
+
+	_, stderr := captureOutput(func() {
+		run(ctx, "test.md", nil, runFn, &stopping, 0)
+	})
+
+	if !strings.Contains(stderr, "Error") {
+		t.Errorf("expected 'Error' in stderr, got: %q", stderr)
+	}
+	if !strings.Contains(stderr, "some error occurred") {
+		t.Errorf("expected error message in stderr, got: %q", stderr)
+	}
+	if !strings.Contains(stderr, "Retrying in") {
+		t.Errorf("expected 'Retrying in' in stderr, got: %q", stderr)
+	}
+	if callCount != 1 {
+		t.Errorf("expected 1 call, got %d", callCount)
+	}
+}
+
+// TestRun_StoppingFlagExits verifies run returns without calling runFn again
+// once stopping is set.
+func TestRun_StoppingFlagExits(t *testing.T) {
+	ctx, cancel := context.WithCancel(context.Background())
+	defer cancel()
+
+	var stopping atomic.Bool
+	callCount := 0
+
+	runFn := func(_ context.Context, _ string, _ []string) error {
+		callCount++
+		stopping.Store(true)
+		return nil
+	}
+
+	done := make(chan struct{})
+	go func() {
+		defer close(done)
+		captureOutput(func() {
+			run(ctx, "test.md", nil, runFn, &stopping, 0)
+		})
+	}()
+
+	select {
+	case <-done:
+		// expected: run returned
+	case <-time.After(500 * time.Millisecond):
+		t.Fatal("run did not return after stopping flag was set")
+	}
+
+	if callCount != 1 {
+		t.Errorf("expected 1 iteration before stopping, got %d", callCount)
+	}
+}
+
+// TestHandleSignals_FirstSignal verifies that the first signal sets stopping
+// but does not cancel the context.
+func TestHandleSignals_FirstSignal(t *testing.T) {
+	ctx, cancel := context.WithCancel(context.Background())
+	defer cancel()
+
+	sigCh := make(chan os.Signal, 2)
+	var stopping atomic.Bool
+
+	// Signal that handleSignals has processed the first signal.
+	processed := make(chan struct{})
+	exitFn := func(int) { close(processed) }
+
+	go func() {
+		captureOutput(func() {
+			handleSignals(sigCh, &stopping, cancel, exitFn)
+		})
+	}()
+
+	sigCh <- os.Interrupt
+
+	// Wait for stopping to be set (poll briefly).
+	deadline := time.Now().Add(200 * time.Millisecond)
+	for time.Now().Before(deadline) {
+		if stopping.Load() {
+			break
+		}
+		time.Sleep(5 * time.Millisecond)
+	}
+
+	if !stopping.Load() {
+		t.Error("expected stopping to be true after first signal")
+	}
+	if ctx.Err() != nil {
+		t.Error("expected context to remain active after first signal")
+	}
+
+	// Send second signal to let the goroutine exit cleanly.
+	sigCh <- os.Interrupt
+	select {
+	case <-processed:
+	case <-time.After(200 * time.Millisecond):
+		t.Error("timeout waiting for handleSignals goroutine to exit")
+	}
+}
+
+// TestHandleSignals_SecondSignal verifies that the second signal cancels the context
+// and calls exitFn(0).
+func TestHandleSignals_SecondSignal(t *testing.T) {
+	ctx, cancel := context.WithCancel(context.Background())
+
+	sigCh := make(chan os.Signal, 2)
+	var stopping atomic.Bool
+
+	var exitCode int
+	var exitCalled bool
+	exitFn := func(code int) {
+		exitCode = code
+		exitCalled = true
+	}
+
+	// Pre-queue both signals so handleSignals processes them synchronously.
+	sigCh <- os.Interrupt
+	sigCh <- os.Interrupt
+
+	captureOutput(func() {
+		handleSignals(sigCh, &stopping, cancel, exitFn)
+	})
+
+	if !stopping.Load() {
+		t.Error("expected stopping to be true")
+	}
+	if ctx.Err() == nil {
+		t.Error("expected context to be cancelled after second signal")
+	}
+	if !exitCalled {
+		t.Error("expected exitFn to be called on second signal")
+	}
+	if exitCode != 0 {
+		t.Errorf("expected exitFn called with 0, got %d", exitCode)
+	}
+}
diff --git a/internal/loop/output.go b/internal/loop/output.go
new file mode 100644
index 0000000..d164a34
--- /dev/null
+++ b/internal/loop/output.go
@@ -0,0 +1,109 @@
+package loop
+
+import (
+	"bufio"
+	"encoding/json"
+	"fmt"
+	"io"
+	"os"
+	"strings"
+)
+
+// printMessages reads stream-JSON from r and formats it for display.
+func printMessages(r io.Reader) {
+	scanner := bufio.NewScanner(r)
+	scanner.Buffer(make([]byte, 0, 4096), maxBufferSize)
+
+	for scanner.Scan() {
+		line := scanner.Text()
+		if line == "" {
+			continue
+		}
+
+		var msg map[string]any
+		if err := json.Unmarshal([]byte(line), &msg); err != nil {
+			continue
+		}
+
+		msgType, _ := msg["type"].(string)
+
+		switch msgType {
+		case "assistant":
+			msgData, ok := msg["message"].(map[string]any)
+			if !ok {
+				continue
+			}
+			contentArray, ok := msgData["content"].([]any)
+			if !ok {
+				continue
+			}
+			for _, item := range contentArray {
+				block, ok := item.(map[string]any)
+				if !ok {
+					continue
+				}
+				blockType, _ := block["type"].(string)
+				switch blockType {
+				case "text":
+					text, _ := block["text"].(string)
+					printSection("Claude", "", text)
+				case "thinking":
+					thinking, _ := block["thinking"].(string)
+					printSection("Claude (thinking)", "", thinking)
+				case "tool_use":
+					name, _ := block["name"].(string)
+					if name == "" {
+						continue
+					}
+					toolName := strings.ToUpper(name[:1]) + name[1:]
+					var content string
+					if input, ok := block["input"].(map[string]any); ok {
+						switch name {
+						case "Bash":
+							content, _ = input["command"].(string)
+						case "Read", "Edit", "Write":
+							content, _ = input["file_path"].(string)
+						case "Grep", "Glob":
+							content, _ = input["pattern"].(string)
+						case "WebFetch":
+							content, _ = input["url"].(string)
+						case "Agent":
+							content, _ = input["prompt"].(string)
+						default:
+							if strings.HasPrefix(name, "Task") {
+								content, _ = input["description"].(string)
+							}
+						}
+					}
+					if content != "" {
+						lines := strings.Split(content, "\n")
+						if len(lines) > 1 {
+							content = lines[0] + fmt.Sprintf("\n... +%d lines", len(lines)-1)
+						}
+					}
+					printSection(toolName, colorGreen, content)
+				}
+			}
+		case "result":
+			isError, _ := msg["is_error"].(bool)
+			if isError {
+				result, _ := msg["result"].(string)
+				printSection("Result (error)", colorRed, result)
+			}
+		}
+	}
+
+	if err := scanner.Err(); err != nil {
+		fmt.Fprintf(os.Stderr, "output parsing error: %v\n", err)
+	}
+}
+
+// printSection outputs a labeled section with optional content.
+func printSection(label, color, content string) {
+	fmt.Printf("%s⏺%s %s%s%s\n", color, colorReset, colorBold, label, colorReset)
+	if content != "" {
+		content = strings.TrimSpace(content)
+		fmt.Printf("%s\n", content)
+	}
+	fmt.Println()
+}
diff --git a/internal/loop/output_test.go b/internal/loop/output_test.go
new file mode 100644
index 0000000..f3ab0b8
--- /dev/null
+++ b/internal/loop/output_test.go
@@ -0,0 +1,226 @@
+package loop
+
+import (
+	"fmt"
+	"strings"
+	"testing"
+)
+
+// TestPrintSection_WithContent verifies ANSI-colored icon, bold label, trimmed content, and trailing blank line.
+func TestPrintSection_WithContent(t *testing.T) {
+	stdout, _ := captureOutput(func() {
+		printSection("MyLabel", colorBlue, "  hello world  ")
+	})
+
+	if !strings.Contains(stdout, colorBlue+"⏺"+colorReset) {
+		t.Errorf("expected colored icon in output, got: %q", stdout)
+	}
+	if !strings.Contains(stdout, colorBold+"MyLabel"+colorReset) {
+		t.Errorf("expected bold label in output, got: %q", stdout)
+	}
+	if !strings.Contains(stdout, "hello world") {
+		t.Errorf("expected content in output, got: %q", stdout)
+	}
+	if strings.Contains(stdout, "  hello world  ") {
+		t.Errorf("expected content to be trimmed, got: %q", stdout)
+	}
+	if !strings.HasSuffix(stdout, "\n\n") {
+		t.Errorf("expected trailing blank line, got: %q", stdout)
+	}
+}
+
+// TestPrintSection_EmptyContent verifies that empty content omits the content line but still prints trailing blank line.
+func TestPrintSection_EmptyContent(t *testing.T) {
+	stdout, _ := captureOutput(func() {
+		printSection("MyLabel", colorGreen, "")
+	})
+
+	if !strings.HasSuffix(stdout, "\n\n") {
+		t.Errorf("expected trailing blank line, got: %q", stdout)
+	}
+	// Output: "header\n\n" → split by \n gives ["header", "", ""] → 3 parts
+	parts := strings.Split(stdout, "\n")
+	if len(parts) != 3 {
+		t.Errorf("expected 3 newline-delimited parts for empty content (header + blank + trailing), got %d: %v", len(parts), parts)
+	}
+}
+
+// TestPrintMessages_AssistantText verifies assistant text blocks display with "Claude" label.
+func TestPrintMessages_AssistantText(t *testing.T) {
+	input := `{"type":"assistant","message":{"content":[{"type":"text","text":"Hello, world!"}]}}` + "\n"
+
+	stdout, _ := captureOutput(func() {
+		printMessages(strings.NewReader(input))
+	})
+
+	if !strings.Contains(stdout, "Claude") {
+		t.Errorf("expected 'Claude' in output, got: %q", stdout)
+	}
+	if !strings.Contains(stdout, "Hello, world!") {
+		t.Errorf("expected text content in output, got: %q", stdout)
+	}
+}
+
+// TestPrintMessages_AssistantThinking verifies thinking blocks display with "Claude (thinking)" label.
+func TestPrintMessages_AssistantThinking(t *testing.T) {
+	input := `{"type":"assistant","message":{"content":[{"type":"thinking","thinking":"Deep thoughts..."}]}}` + "\n"
+
+	stdout, _ := captureOutput(func() {
+		printMessages(strings.NewReader(input))
+	})
+
+	if !strings.Contains(stdout, "Claude (thinking)") {
+		t.Errorf("expected 'Claude (thinking)' in output, got: %q", stdout)
+	}
+	if !strings.Contains(stdout, "Deep thoughts...") {
+		t.Errorf("expected thinking content in output, got: %q", stdout)
+	}
+}
+
+// TestPrintMessages_ToolUse verifies tool_use blocks display with correct label, input content, and green color.
+func TestPrintMessages_ToolUse(t *testing.T) {
+	tests := []struct {
+		toolName   string
+		inputKey   string
+		inputValue string
+	}{
+		{"Bash", "command", "ls -la"},
+		{"Read", "file_path", "/path/to/file.go"},
+		{"Edit", "file_path", "/path/to/edit.go"},
+		{"Write", "file_path", "/path/to/write.go"},
+		{"Grep", "pattern", "func.*main"},
+		{"Glob", "pattern", "**/*.go"},
+		{"WebFetch", "url", "https://example.com"},
+		{"TaskCreate", "description", "do something important"},
+		{"Agent", "prompt", "run this agent now"},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.toolName, func(t *testing.T) {
+			input := fmt.Sprintf(`{"type":"assistant","message":{"content":[{"type":"tool_use","name":%q,"input":{%q:%q}}]}}`,
+				tt.toolName, tt.inputKey, tt.inputValue) + "\n"
+
+			stdout, _ := captureOutput(func() {
+				printMessages(strings.NewReader(input))
+			})
+
+			if !strings.Contains(stdout, tt.toolName) {
+				t.Errorf("expected tool name %q in output, got: %q", tt.toolName, stdout)
+			}
+			if !strings.Contains(stdout, tt.inputValue) {
+				t.Errorf("expected input value %q in output, got: %q", tt.inputValue, stdout)
+			}
+			if !strings.Contains(stdout, colorGreen) {
+				t.Errorf("expected green color for tool section, got: %q", stdout)
+			}
+		})
+	}
+}
+
+// TestPrintMessages_UnknownTool verifies that unknown tools display header only with no content.
+func TestPrintMessages_UnknownTool(t *testing.T) {
+	input := `{"type":"assistant","message":{"content":[{"type":"tool_use","name":"UnknownTool","input":{"foo":"bar"}}]}}` + "\n"
+
+	stdout, _ := captureOutput(func() {
+		printMessages(strings.NewReader(input))
+	})
+
+	if !strings.Contains(stdout, "UnknownTool") {
+		t.Errorf("expected tool name 'UnknownTool' in output, got: %q", stdout)
+	}
+	if strings.Contains(stdout, "bar") {
+		t.Errorf("expected no content for unknown tool, got: %q", stdout)
+	}
+}
+
+// TestPrintMessages_ErrorResult verifies error result messages display with "Result (error)" label and red color.
+func TestPrintMessages_ErrorResult(t *testing.T) {
+	input := `{"type":"result","is_error":true,"result":"something went wrong"}` + "\n"
+
+	stdout, _ := captureOutput(func() {
+		printMessages(strings.NewReader(input))
+	})
+
+	if !strings.Contains(stdout, "Result (error)") {
+		t.Errorf("expected 'Result (error)' in output, got: %q", stdout)
+	}
+	if !strings.Contains(stdout, "something went wrong") {
+		t.Errorf("expected error text in output, got: %q", stdout)
+	}
+	if !strings.Contains(stdout, colorRed) {
+		t.Errorf("expected red color for error section, got: %q", stdout)
+	}
+}
+
+// TestPrintMessages_NonErrorResult verifies non-error result messages are silently skipped.
+func TestPrintMessages_NonErrorResult(t *testing.T) {
+	input := `{"type":"result","is_error":false,"result":"done"}` + "\n"
+
+	stdout, _ := captureOutput(func() {
+		printMessages(strings.NewReader(input))
+	})
+
+	if stdout != "" {
+		t.Errorf("expected no output for non-error result, got: %q", stdout)
+	}
+}
+
+// TestPrintMessages_UnknownType verifies unknown message types are silently skipped.
+func TestPrintMessages_UnknownType(t *testing.T) {
+	input := `{"type":"system","content":"some system message"}` + "\n"
+
+	stdout, _ := captureOutput(func() {
+		printMessages(strings.NewReader(input))
+	})
+
+	if stdout != "" {
+		t.Errorf("expected no output for unknown message type, got: %q", stdout)
+	}
+}
+
+// TestPrintMessages_MalformedJSON verifies malformed JSON lines are silently skipped.
+func TestPrintMessages_MalformedJSON(t *testing.T) {
+	input := "not valid json\n"
+
+	stdout, _ := captureOutput(func() {
+		printMessages(strings.NewReader(input))
+	})
+
+	if stdout != "" {
+		t.Errorf("expected no output for malformed JSON, got: %q", stdout)
+	}
+}
+
+// TestPrintMessages_ScannerError verifies that a scanner error (e.g., line exceeding maxBufferSize) prints to stderr.
+func TestPrintMessages_ScannerError(t *testing.T) {
+	// Create a line longer than maxBufferSize to trigger a scanner buffer overflow.
+	oversized := strings.Repeat("x", maxBufferSize+1) + "\n"
+
+	_, stderr := captureOutput(func() {
+		printMessages(strings.NewReader(oversized))
+	})
+
+	if !strings.Contains(stderr, "output parsing error") {
+		t.Errorf("expected 'output parsing error' in stderr, got: %q", stderr)
+	}
+}
+
+// TestPrintMessages_MultiLineTruncation verifies multi-line tool input is truncated to first line plus count.
+func TestPrintMessages_MultiLineTruncation(t *testing.T) {
+	multiLineCmd := "line1\nline2\nline3"
+	input := fmt.Sprintf(`{"type":"assistant","message":{"content":[{"type":"tool_use","name":"Bash","input":{"command":%q}}]}}`, multiLineCmd) + "\n"
+
+	stdout, _ := captureOutput(func() {
+		printMessages(strings.NewReader(input))
+	})
+
+	if !strings.Contains(stdout, "line1") {
+		t.Errorf("expected first line in output, got: %q", stdout)
+	}
+	if !strings.Contains(stdout, "... +2 lines") {
+		t.Errorf("expected truncation indicator '... +2 lines', got: %q", stdout)
+	}
+	if strings.Contains(stdout, "line2") || strings.Contains(stdout, "line3") {
+		t.Errorf("expected subsequent lines to be truncated, got: %q", stdout)
+	}
+}
diff --git a/internal/task/cmd.go b/internal/task/cmd.go
new file mode 100644
index 0000000..1f92ab3
--- /dev/null
+++ b/internal/task/cmd.go
@@ -0,0 +1,508 @@
+package task
+
+import (
+	"flag"
+	"fmt"
+	"io"
+	"os"
+	"strings"
+	"time"
+)
+
+// multiFlag is a []string implementing flag.Value for repeatable flags.
+type multiFlag []string
+
+func (f *multiFlag) String() string {
+	return strings.Join(*f, ",")
+}
+
+func (f *multiFlag) Set(s string) error {
+	*f = append(*f, s)
+	return nil
+}
+
+// validStatus returns true if s is a valid TaskStatus.
+func validStatus(s string) bool {
+	switch TaskStatus(s) {
+	case StatusPending, StatusInProgress, StatusCompleted:
+		return true
+	}
+	return false
+}
+
+// HandleTask dispatches lorah task subcommands.
+// It returns an exit code: 0 for success, 1 for error.
+func HandleTask(args []string, w io.Writer, storage Storage) int {
+	if len(args) == 0 {
+		fmt.Fprintln(os.Stderr, "usage: lorah task <subcommand> [args...]")
+		return 1
+	}
+	switch args[0] {
+	case "--help", "-help", "-h":
+		fmt.Fprintln(os.Stderr, "usage: lorah task <subcommand> [args...]")
+		return 0
+	case "list":
+		return listCmd(args[1:], w, storage)
+	case "get":
+		return getCmd(args[1:], w, storage)
+	case "create":
+		return createCmd(args[1:], w, storage)
+	case "update":
+		return updateCmd(args[1:], w, storage)
+	case "delete":
+		return deleteCmd(args[1:], w, storage)
+	case "export":
+		return exportCmd(args[1:], w, storage)
+	default:
+		fmt.Fprintf(os.Stderr, "Unknown subcommand: %s\n", args[0])
+		return 1
+	}
+}
+
+func listCmd(args []string, w io.Writer, storage Storage) int {
+	fs := flag.NewFlagSet("lorah task list", flag.ContinueOnError)
+	var statuses multiFlag
+	fs.Var(&statuses, "status", "filter by status (repeatable)")
+	phase := fs.String("phase", "", "filter by phase ID")
+	section := fs.String("section", "", "filter by section ID")
+	limit := fs.Int("limit", 0, "maximum number of results (0 = no limit)")
+	flat := fs.Bool("flat", false, "flat bullet list, no headings or notes")
+	format := fs.String("format", "markdown", "output format (markdown|json)")
+	if err := fs.Parse(args); err != nil {
+		return 1
+	}
+
+	var statusFilter []TaskStatus
+	for _, s := range statuses {
+		if !validStatus(s) {
+			fmt.Fprintf(os.Stderr, "invalid status: %s\n", s)
+			return 1
+		}
+		statusFilter = append(statusFilter, TaskStatus(s))
+	}
+
+	filter := Filter{
+		Status:    statusFilter,
+		PhaseID:   *phase,
+		SectionID: *section,
+		Limit:     *limit,
+	}
+
+	tasks, err := storage.List(filter)
+	if err != nil {
+		fmt.Fprintf(os.Stderr, "error listing tasks: %v\n", err)
+		return 1
+	}
+
+	list, err := storage.Load()
+	if err != nil {
+		fmt.Fprintf(os.Stderr, "error loading task list: %v\n", err)
+		return 1
+	}
+
+	var out string
+	switch *format {
+	case "json":
+		out, err = FormatListJSON(tasks)
+		if err != nil {
+			fmt.Fprintf(os.Stderr, "error formatting JSON: %v\n", err)
+			return 1
+		}
+	default:
+		out = FormatListMarkdown(tasks, list, *flat)
+	}
+
+	fmt.Fprint(w, out)
+	return 0
+}
+
+func getCmd(args []string, w io.Writer, storage Storage) int {
+	if len(args) == 0 || strings.HasPrefix(args[0], "-") {
+		fmt.Fprintln(os.Stderr, "usage: lorah task get <id> [--format=json|markdown]")
+		return 1
+	}
+	id := args[0]
+
+	fs := flag.NewFlagSet("lorah task get", flag.ContinueOnError)
+	format := fs.String("format", "markdown", "output format (markdown|json)")
+	if err := fs.Parse(args[1:]); err != nil {
+		return 1
+	}
+
+	task, err := storage.Get(id)
+	if err != nil {
+		fmt.Fprintf(os.Stderr, "error: %v\n", err)
+		return 1
+	}
+
+	list, err := storage.Load()
+	if err != nil {
+		fmt.Fprintf(os.Stderr, "error loading task list: %v\n", err)
+		return 1
+	}
+
+	var out string
+	switch *format {
+	case "json":
+		out, err = FormatTaskJSON(task)
+		if err != nil {
+			fmt.Fprintf(os.Stderr, "error formatting JSON: %v\n", err)
+			return 1
+		}
+	default:
+		out = FormatTaskMarkdown(task, list)
+	}
+
+	fmt.Fprint(w, out)
+	return 0
+}
+
+func createCmd(args []string, w io.Writer, storage Storage) int {
+	fs := flag.NewFlagSet("lorah task create", flag.ContinueOnError)
+	subject := fs.String("subject", "", "task subject (required)")
+	status := fs.String("status", "pending", "task status")
+	phase := fs.String("phase", "", "existing phase ID")
+	phaseName := fs.String("phase-name", "", "phase name (creates new phase if --phase omitted)")
+	phaseDesc := fs.String("phase-description", "", "phase description")
+	section := fs.String("section", "", "existing section ID")
+	sectionName := fs.String("section-name", "", "section name (creates new section if --section omitted)")
+	sectionDesc := fs.String("section-description", "", "section description")
+	projectName := fs.String("project-name", "", "project name")
+	projectDesc := fs.String("project-description", "", "project description")
+	if err := fs.Parse(args); err != nil {
+		return 1
+	}
+
+	if *subject == "" {
+		fmt.Fprintln(os.Stderr, "--subject is required")
+		return 1
+	}
+	if !validStatus(*status) {
+		fmt.Fprintf(os.Stderr, "invalid status: %s\n", *status)
+		return 1
+	}
+
+	list, err := storage.Load()
+	if err != nil {
+		fmt.Fprintf(os.Stderr, "error loading task list: %v\n", err)
+		return 1
+	}
+
+	listModified := false
+
+	if *projectName != "" {
+		list.Name = *projectName
+		listModified = true
+	}
+	if *projectDesc != "" {
+		list.Description = *projectDesc
+		listModified = true
+	}
+
+	// Resolve or create phase.
+	var phaseID string
+	var newPhaseID string
+	if *phase != "" {
+		phaseID = *phase
+		if *phaseName != "" || *phaseDesc != "" {
+			for i, p := range list.Phases {
+				if p.ID == phaseID {
+					if *phaseName != "" {
+						list.Phases[i].Name = *phaseName
+					}
+					if *phaseDesc != "" {
+						list.Phases[i].Description = *phaseDesc
+					}
+					listModified = true
+					break
+				}
+			}
+		}
+	} else if *phaseName != "" || *phaseDesc != "" {
+		newPhaseID = generateID()
+		phaseID = newPhaseID
+		p := Phase{ID: newPhaseID}
+		if *phaseName != "" {
+			p.Name = *phaseName
+		}
+		if *phaseDesc != "" {
+			p.Description = *phaseDesc
+		}
+		list.Phases = append(list.Phases, p)
+		listModified = true
+	}
+
+	// Resolve or create section.
+	var sectionID string
+	var newSectionID string
+	if *section != "" {
+		if phaseID == "" {
+			fmt.Fprintln(os.Stderr, "--section requires a phase context (--phase or --phase-name)")
+			return 1
+		}
+		sectionID = *section
+		if *sectionName != "" || *sectionDesc != "" {
+			for i, s := range list.Sections {
+				if s.ID == sectionID {
+					if *sectionName != "" {
+						list.Sections[i].Name = *sectionName
+					}
+					if *sectionDesc != "" {
+						list.Sections[i].Description = *sectionDesc
+					}
+					listModified = true
+					break
+				}
+			}
+		}
+	} else if *sectionName != "" || *sectionDesc != "" {
+		if phaseID == "" {
+			fmt.Fprintln(os.Stderr, "--section-name requires a phase context (--phase or --phase-name)")
+			return 1
+		}
+		newSectionID = generateID()
+		sectionID = newSectionID
+		s := Section{ID: newSectionID, PhaseID: phaseID}
+		if *sectionName != "" {
+			s.Name = *sectionName
+		}
+		if *sectionDesc != "" {
+			s.Description = *sectionDesc
+		}
+		list.Sections = append(list.Sections, s)
+		listModified = true
+	}
+
+	if listModified {
+		if err := storage.Save(list); err != nil {
+			fmt.Fprintf(os.Stderr, "error saving task list: %v\n", err)
+			return 1
+		}
+	}
+
+	task := &Task{
+		ID:          generateID(),
+		Subject:     *subject,
+		Status:      TaskStatus(*status),
+		PhaseID:     phaseID,
+		SectionID:   sectionID,
+		LastUpdated: time.Now(),
+	}
+	if err := storage.Create(task); err != nil {
+		fmt.Fprintf(os.Stderr, "error creating task: %v\n", err)
+		return 1
+	}
+
+	if newPhaseID != "" {
+		fmt.Fprintf(w, "phase %s\n", newPhaseID)
+	}
+	if newSectionID != "" {
+		fmt.Fprintf(w, "section %s\n", newSectionID)
+	}
+	fmt.Fprintf(w, "task %s\n", task.ID)
+	return 0
+}
+
+func updateCmd(args []string, w io.Writer, storage Storage) int {
+	if len(args) == 0 || strings.HasPrefix(args[0], "-") {
+		fmt.Fprintln(os.Stderr, "usage: lorah task update <id> [flags...]")
+		return 1
+	}
+	id := args[0]
+
+	fs := flag.NewFlagSet("lorah task update", flag.ContinueOnError)
+	statusFlag := fs.String("status", "", "task status")
+	subjectFlag := fs.String("subject", "", "task subject")
+	notesFlag := fs.String("notes", "", "task notes")
+	phaseFlag := fs.String("phase", "", "existing phase ID")
+	phaseNameFlag := fs.String("phase-name", "", "phase name")
+	phaseDescFlag := fs.String("phase-description", "", "phase description")
+	sectionFlag := fs.String("section", "", "existing section ID")
+	sectionNameFlag := fs.String("section-name", "", "section name")
+	sectionDescFlag := fs.String("section-description", "", "section description")
+	projectNameFlag := fs.String("project-name", "", "project name")
+	projectDescFlag := fs.String("project-description", "", "project description")
+	if err := fs.Parse(args[1:]); err != nil {
+		return 1
+	}
+
+	provided := map[string]bool{}
+	fs.Visit(func(f *flag.Flag) { provided[f.Name] = true })
+
+	if provided["status"] && !validStatus(*statusFlag) {
+		fmt.Fprintf(os.Stderr, "invalid status: %s\n", *statusFlag)
+		return 1
+	}
+	if provided["phase-name"] && !provided["phase"] {
+		fmt.Fprintln(os.Stderr, "--phase-name requires --phase")
+		return 1
+	}
+	if provided["phase-description"] && !provided["phase"] {
+		fmt.Fprintln(os.Stderr, "--phase-description requires --phase")
+		return 1
+	}
+	if provided["section"] && !provided["phase"] {
+		fmt.Fprintln(os.Stderr, "--section requires --phase")
+		return 1
+	}
+	if provided["section-name"] && !provided["section"] {
+		fmt.Fprintln(os.Stderr, "--section-name requires --section")
+		return 1
+	}
+	if provided["section-description"] && !provided["section"] {
+		fmt.Fprintln(os.Stderr, "--section-description requires --section")
+		return 1
+	}
+
+	task, err := storage.Get(id)
+	if err != nil {
+		fmt.Fprintf(os.Stderr, "error: %v\n", err)
+		return 1
+	}
+
+	if provided["status"] {
+		task.Status = TaskStatus(*statusFlag)
+	}
+	if provided["subject"] {
+		task.Subject = *subjectFlag
+	}
+	if provided["notes"] {
+		task.Notes = *notesFlag
+	}
+	if provided["phase"] {
+		task.PhaseID = *phaseFlag
+	}
+	if provided["section"] {
+		task.SectionID = *sectionFlag
+	}
+	task.LastUpdated = time.Now()
+
+	if err := storage.Update(task); err != nil {
+		fmt.Fprintf(os.Stderr, "error updating task: %v\n", err)
+		return 1
+	}
+
+	// Handle list-level mutations.
+	needsList := provided["project-name"] || provided["project-description"] ||
+		provided["phase-name"] || provided["phase-description"] ||
+		provided["section-name"] || provided["section-description"]
+	if needsList {
+		list, err := storage.Load()
+		if err != nil {
+			fmt.Fprintf(os.Stderr, "error loading task list: %v\n", err)
+			return 1
+		}
+		listModified := false
+		if provided["project-name"] {
+			list.Name = *projectNameFlag
+			listModified = true
+		}
+		if provided["project-description"] {
+			list.Description = *projectDescFlag
+			listModified = true
+		}
+		if provided["phase-name"] && provided["phase"] {
+			for i, p := range list.Phases {
+				if p.ID == *phaseFlag {
+					list.Phases[i].Name = *phaseNameFlag
+					listModified = true
+					break
+				}
+			}
+		}
+		if provided["phase-description"] && provided["phase"] {
+			for i, p := range list.Phases {
+				if p.ID == *phaseFlag {
+					list.Phases[i].Description = *phaseDescFlag
+					listModified = true
+					break
+				}
+			}
+		}
+		if provided["section-name"] && provided["section"] {
+			for i, s := range list.Sections {
+				if s.ID == *sectionFlag {
+					list.Sections[i].Name = *sectionNameFlag
+					listModified = true
+					break
+				}
+			}
+		}
+		if provided["section-description"] && provided["section"] {
+			for i, s := range list.Sections {
+				if s.ID == *sectionFlag {
+					list.Sections[i].Description = *sectionDescFlag
+					listModified = true
+					break
+				}
+			}
+		}
+		if listModified {
+			if err := storage.Save(list); err != nil {
+				fmt.Fprintf(os.Stderr, "error saving task list: %v\n", err)
+				return 1
+			}
+		}
+	}
+
+	_ = w
+	return 0
+}
+
+func deleteCmd(args []string, w io.Writer, storage Storage) int {
+	_ = w
+	if len(args) == 0 || strings.HasPrefix(args[0], "-") {
+		fmt.Fprintln(os.Stderr, "usage: lorah task delete <id>")
+		return 1
+	}
+	id := args[0]
+	if err := storage.Delete(id); err != nil {
+		fmt.Fprintf(os.Stderr, "error: %v\n", err)
+		return 1
+	}
+	return 0
+}
+
+func exportCmd(args []string, w io.Writer, storage Storage) int {
+	fs := flag.NewFlagSet("lorah task export", flag.ContinueOnError)
+	var statuses multiFlag
+	fs.Var(&statuses, "status", "filter by status (repeatable)")
+	output := fs.String("output", "", "output file path (default stdout)")
+	if err := fs.Parse(args); err != nil {
+		return 1
+	}
+
+	var statusFilter []TaskStatus
+	for _, s := range statuses {
+		if !validStatus(s) {
+			fmt.Fprintf(os.Stderr, "invalid status: %s\n", s)
+			return 1
+		}
+		statusFilter = append(statusFilter, TaskStatus(s))
+	}
+
+	tasks, err := storage.List(Filter{Status: statusFilter})
+	if err != nil {
+		fmt.Fprintf(os.Stderr, "error listing tasks: %v\n", err)
+		return 1
+	}
+
+	list, err := storage.Load()
+	if err != nil {
+		fmt.Fprintf(os.Stderr, "error loading task list: %v\n", err)
+		return 1
+	}
+
+	out := FormatExportMarkdown(tasks, list)
+
+	if *output != "" {
+		if err := os.WriteFile(*output, []byte(out), 0644); err != nil {
+			fmt.Fprintf(os.Stderr, "error writing output file: %v\n", err)
+			return 1
+		}
+		return 0
+	}
+
+	fmt.Fprint(w, out)
+	return 0
+}
diff --git a/internal/task/cmd_test.go b/internal/task/cmd_test.go
new file mode 100644
index 0000000..1ddd792
--- /dev/null
+++ b/internal/task/cmd_test.go
@@ -0,0 +1,1228 @@
+package task
+
+import (
+	"bytes"
+	"errors"
+	"strings"
+	"testing"
+	"time"
+)
+
+// mockStorage implements Storage for test isolation.
+type mockStorage struct {
+	list    *TaskList
+	tasks   map[string]*Task
+	loadErr error
+	saveErr error
+}
+
+func newMockStorage() *mockStorage {
+	return &mockStorage{
+		list:  &TaskList{Version: "1.0"},
+		tasks: make(map[string]*Task),
+	}
+}
+
+func (m *mockStorage) Load() (*TaskList, error) {
+	if m.loadErr != nil {
+		return nil, m.loadErr
+	}
+	return m.list, nil
+}
+
+func (m *mockStorage) Save(list *TaskList) error {
+	if m.saveErr != nil {
+		return m.saveErr
+	}
+	m.list = list
+	return nil
+}
+
+func (m *mockStorage) Get(id string) (*Task, error) {
+	t, ok := m.tasks[id]
+	if !ok {
+		return nil, errors.New("task not found: " + id)
+	}
+	return t, nil
+}
+
+func (m *mockStorage) List(filter Filter) ([]Task, error) {
+	if m.loadErr != nil {
+		return nil, m.loadErr
+	}
+	var result []Task
+	for _, t := range m.list.Tasks {
+		if len(filter.Status) > 0 {
+			match := false
+			for _, s := range filter.Status {
+				if t.Status == s {
+					match = true
+					break
+				}
+			}
+			if !match {
+				continue
+			}
+		}
+		if filter.PhaseID != "" && t.PhaseID != filter.PhaseID {
+			continue
+		}
+		if filter.SectionID != "" && t.SectionID != filter.SectionID {
+			continue
+		}
+		result = append(result, t)
+		if filter.Limit > 0 && len(result) >= filter.Limit {
+			break
+		}
+	}
+	return result, nil
+}
+
+func (m *mockStorage) Create(task *Task) error {
+	if _, ok := m.tasks[task.ID]; ok {
+		return errors.New("duplicate id: " + task.ID)
+	}
+	m.tasks[task.ID] = task
+	m.list.Tasks = append(m.list.Tasks, *task)
+	return nil
+}
+
+func (m *mockStorage) Update(task *Task) error {
+	if _, ok := m.tasks[task.ID]; !ok {
+		return errors.New("task not found: " + task.ID)
+	}
+	m.tasks[task.ID] = task
+	for i, t := range m.list.Tasks {
+		if t.ID == task.ID {
+			m.list.Tasks[i] = *task
+			break
+		}
+	}
+	return nil
+}
+
+func (m *mockStorage) Delete(id string) error {
+	if _, ok := m.tasks[id]; !ok {
+		return errors.New("task not found: " + id)
+	}
+	delete(m.tasks, id)
+	for i, t := range m.list.Tasks {
+		if t.ID == id {
+			m.list.Tasks = append(m.list.Tasks[:i], m.list.Tasks[i+1:]...)
+			break
+		}
+	}
+	return nil
+}
+
+// --- multiFlag tests ---
+
+func TestMultiFlagString(t *testing.T) {
+	var f multiFlag
+	if f.String() != "" {
+		t.Errorf("expected empty string, got %q", f.String())
+	}
+	f = multiFlag{"a", "b"}
+	got := f.String()
+	if got != "a,b" {
+		t.Errorf("expected %q, got %q", "a,b", got)
+	}
+}
+
+func TestMultiFlagSet(t *testing.T) {
+	var f multiFlag
+	if err := f.Set("foo"); err != nil {
+		t.Fatal(err)
+	}
+	if err := f.Set("bar"); err != nil {
+		t.Fatal(err)
+	}
+	if len(f) != 2 || f[0] != "foo" || f[1] != "bar" {
+		t.Errorf("unexpected values: %v", f)
+	}
+}
+
+// --- HandleTask dispatch tests ---
+
+func TestHandleTaskHelp(t *testing.T) {
+	for _, arg := range []string{"--help", "-h"} {
+		var buf bytes.Buffer
+		code := HandleTask([]string{arg}, &buf, newMockStorage())
+		if code != 0 {
+			t.Errorf("HandleTask(%q): expected exit 0, got %d", arg, code)
+		}
+	}
+}
+
+func TestHandleTaskUnknownSubcommand(t *testing.T) {
+	var buf bytes.Buffer
+	code := HandleTask([]string{"bogus"}, &buf, newMockStorage())
+	if code != 1 {
+		t.Errorf("expected exit 1, got %d", code)
+	}
+}
+
+func TestHandleTaskNoArgs(t *testing.T) {
+	var buf bytes.Buffer
+	code := HandleTask([]string{}, &buf, newMockStorage())
+	if code != 1 {
+		t.Errorf("expected exit 1, got %d", code)
+	}
+}
+
+// --- list tests ---
+
+func TestListBasic(t *testing.T) {
+	store := newMockStorage()
+	now := time.Now()
+	task := &Task{ID: "aabbccdd", Subject: "Do something", Status: StatusPending, LastUpdated: now}
+	store.list.Tasks = []Task{*task}
+	store.tasks["aabbccdd"] = task
+
+	var buf bytes.Buffer
+	code := HandleTask([]string{"list"}, &buf, store)
+	if code != 0 {
+		t.Errorf("expected exit 0, got %d", code)
+	}
+	out := buf.String()
+	if !strings.Contains(out, "aabbccdd") {
+		t.Errorf("expected task ID in output, got:\n%s", out)
+	}
+}
+
+func TestListStatusFilter(t *testing.T) {
+	store := newMockStorage()
+	now := time.Now()
+	store.list.Tasks = []Task{
+		{ID: "aaaaaa01", Subject: "Pending task", Status: StatusPending, LastUpdated: now},
+		{ID: "aaaaaa02", Subject: "Completed task", Status: StatusCompleted, LastUpdated: now},
+	}
+
+	var buf bytes.Buffer
+	code := HandleTask([]string{"list", "--status=pending"}, &buf, store)
+	if code != 0 {
+		t.Errorf("expected exit 0, got %d", code)
+	}
+	out := buf.String()
+	if !strings.Contains(out, "aaaaaa01") {
+		t.Errorf("expected pending task in output")
+	}
+	if strings.Contains(out, "aaaaaa02") {
+		t.Errorf("expected completed task to be filtered out")
+	}
+}
+
+func TestListMultipleStatusFlags(t *testing.T) {
+	store := newMockStorage()
+	now := time.Now()
+	store.list.Tasks = []Task{
+		{ID: "aaaaaa01", Subject: "Pending", Status: StatusPending, LastUpdated: now},
+		{ID: "aaaaaa02", Subject: "In progress", Status: StatusInProgress, LastUpdated: now},
+		{ID: "aaaaaa03", Subject: "Completed", Status: StatusCompleted, LastUpdated: now},
+	}
+
+	var buf bytes.Buffer
+	code := HandleTask([]string{"list", "--status=pending", "--status=in_progress"}, &buf, store)
+	if code != 0 {
+		t.Errorf("expected exit 0, got %d", code)
+	}
+	out := buf.String()
+	if !strings.Contains(out, "aaaaaa01") || !strings.Contains(out, "aaaaaa02") {
+		t.Errorf("expected pending and in_progress tasks in output")
+	}
+	if strings.Contains(out, "aaaaaa03") {
+		t.Errorf("expected completed task to be filtered out")
+	}
+}
+
+func TestListFlatFormat(t *testing.T) {
+	store := newMockStorage()
+	now := time.Now()
+	store.list.Tasks = []Task{
+		{ID: "aaaaaa01", Subject: "Task A", Status: StatusPending, LastUpdated: now, Notes: "some notes"},
+	}
+
+	var buf bytes.Buffer
+	code := HandleTask([]string{"list", "--flat"}, &buf, store)
+	if code != 0 {
+		t.Errorf("expected exit 0, got %d", code)
+	}
+	out := buf.String()
+	if strings.Contains(out, "notes") {
+		t.Errorf("expected notes to be suppressed in flat mode, got:\n%s", out)
+	}
+	if strings.Contains(out, "##") {
+		t.Errorf("expected no headings in flat mode, got:\n%s", out)
+	}
+}
+
+func TestListJSONFormat(t *testing.T) {
+	store := newMockStorage()
+	now := time.Now()
+	store.list.Tasks = []Task{
+		{ID: "aaaaaa01", Subject: "Task A", Status: StatusPending, LastUpdated: now},
+	}
+
+	var buf bytes.Buffer
+	code := HandleTask([]string{"list", "--format=json"}, &buf, store)
+	if code != 0 {
+		t.Errorf("expected exit 0, got %d", code)
+	}
+	out := buf.String()
+	if !strings.Contains(out, `"tasks"`) {
+		t.Errorf("expected JSON envelope with tasks key, got:\n%s", out)
+	}
+}
+
+func TestListPhaseFilter(t *testing.T) {
+	store := newMockStorage()
+	now := time.Now()
+	store.list.Tasks = []Task{
+		{ID: "aaaaaa01", Subject: "Phase1 task", Status: StatusPending, PhaseID: "phase111", LastUpdated: now},
+		{ID: "aaaaaa02", Subject: "Phase2 task", Status: StatusPending, PhaseID: "phase222", LastUpdated: now},
+	}
+
+	var buf bytes.Buffer
+	code := HandleTask([]string{"list", "--phase=phase111"}, &buf, store)
+	if code != 0 {
+		t.Errorf("expected exit 0, got %d", code)
+	}
+	out := buf.String()
+	if !strings.Contains(out, "aaaaaa01") {
+		t.Errorf("expected phase1 task in output")
+	}
+	if strings.Contains(out, "aaaaaa02") {
+		t.Errorf("expected phase2 task to be filtered out")
+	}
+}
+
+func TestListLimit(t *testing.T) {
+	store := newMockStorage()
+	now := time.Now()
+	store.list.Tasks = []Task{
+		{ID: "aaaaaa01", Subject: "Task 1", Status: StatusPending, LastUpdated: now},
+		{ID: "aaaaaa02", Subject: "Task 2", Status: StatusPending, LastUpdated: now},
+		{ID: "aaaaaa03", Subject: "Task 3", Status: StatusPending, LastUpdated: now},
+	}
+
+	var buf bytes.Buffer
+	code := HandleTask([]string{"list", "--limit=2"}, &buf, store)
+	if code != 0 {
+		t.Errorf("expected exit 0, got %d", code)
+	}
+	out := buf.String()
+	count := strings.Count(out, "aaaaaa")
+	if count != 2 {
+		t.Errorf("expected 2 tasks with limit=2, got %d in:\n%s", count, out)
+	}
+}
+
+func TestListSectionFilter(t *testing.T) {
+	store := newMockStorage()
+	now := time.Now()
+	store.list.Tasks = []Task{
+		{ID: "aaaaaa01", Subject: "Section1 task", Status: StatusPending, SectionID: "sect1111", LastUpdated: now},
+		{ID: "aaaaaa02", Subject: "Section2 task", Status: StatusPending, SectionID: "sect2222", LastUpdated: now},
+	}
+
+	var buf bytes.Buffer
+	code := HandleTask([]string{"list", "--section=sect1111"}, &buf, store)
+	if code != 0 {
+		t.Errorf("expected exit 0, got %d", code)
+	}
+	out := buf.String()
+	if !strings.Contains(out, "aaaaaa01") {
+		t.Errorf("expected section1 task in output")
+	}
+	if strings.Contains(out, "aaaaaa02") {
+		t.Errorf("expected section2 task to be filtered out")
+	}
+}
+
+func TestListFlatWithJSON(t *testing.T) {
+	store := newMockStorage()
+	now := time.Now()
+	store.list.Tasks = []Task{
+		{ID: "aaaaaa01", Subject: "Task A", Status: StatusPending, LastUpdated: now, Notes: "some notes"},
+	}
+
+	var buf bytes.Buffer
+	code := HandleTask([]string{"list", "--flat", "--format=json"}, &buf, store)
+	if code != 0 {
+		t.Errorf("expected exit 0, got %d", code)
+	}
+	out := buf.String()
+	// --flat is ignored when --format=json; output should be JSON envelope
+	if !strings.Contains(out, `"tasks"`) {
+		t.Errorf("expected JSON envelope with tasks key even with --flat, got:\n%s", out)
+	}
+}
+
+func TestListInvalidStatus(t *testing.T) {
+	store := newMockStorage()
+
+	var buf bytes.Buffer
+	code := HandleTask([]string{"list", "--status=bogus"}, &buf, store)
+	if code != 1 {
+		t.Errorf("expected exit 1 for invalid status, got %d", code)
+	}
+}
+
+// --- get tests ---
+
+func TestGetByID(t *testing.T) {
+	store := newMockStorage()
+	now := time.Now()
+	task := &Task{ID: "deadbeef", Subject: "Test get", Status: StatusPending, LastUpdated: now}
+	store.tasks["deadbeef"] = task
+	store.list = &TaskList{Version: "1.0", Tasks: []Task{*task}}
+
+	var buf bytes.Buffer
+	code := HandleTask([]string{"get", "deadbeef"}, &buf, store)
+	if code != 0 {
+		t.Errorf("expected exit 0, got %d", code)
+	}
+	out := buf.String()
+	// Default format is markdown; subject should appear as H1.
+	if !strings.Contains(out, "# Test get") {
+		t.Errorf("expected subject as H1 in markdown output, got:\n%s", out)
+	}
+}
+
+func TestGetCmdNotFound(t *testing.T) {
+	store := newMockStorage()
+
+	var buf bytes.Buffer
+	code := HandleTask([]string{"get", "notexist"}, &buf, store)
+	if code != 1 {
+		t.Errorf("expected exit 1 for missing task, got %d", code)
+	}
+}
+
+func TestGetMissingID(t *testing.T) {
+	store := newMockStorage()
+
+	var buf bytes.Buffer
+	code := HandleTask([]string{"get"}, &buf, store)
+	if code != 1 {
+		t.Errorf("expected exit 1 when ID not provided, got %d", code)
+	}
+}
+
+func TestGetJSONFormat(t *testing.T) {
+	store := newMockStorage()
+	now := time.Now()
+	task := &Task{ID: "deadbeef", Subject: "Test get JSON", Status: StatusPending, LastUpdated: now}
+	store.tasks["deadbeef"] = task
+	store.list = &TaskList{Version: "1.0", Tasks: []Task{*task}}
+
+	var buf bytes.Buffer
+	code := HandleTask([]string{"get", "deadbeef", "--format=json"}, &buf, store)
+	if code != 0 {
+		t.Errorf("expected exit 0, got %d", code)
+	}
+	out := buf.String()
+	if !strings.Contains(out, `"id"`) || !strings.Contains(out, "deadbeef") {
+		t.Errorf("expected JSON with task fields, got:\n%s", out)
+	}
+	// Should NOT be wrapped in {"tasks": [...]}
+	if strings.Contains(out, `"tasks"`) {
+		t.Errorf("get JSON should not be wrapped in tasks envelope, got:\n%s", out)
+	}
+}
+
+// --- create tests ---
+
+func TestCreateRequiresSubject(t *testing.T) {
+	store := newMockStorage()
+
+	var buf bytes.Buffer
+	code := HandleTask([]string{"create"}, &buf, store)
+	if code != 1 {
+		t.Errorf("expected exit 1 when --subject missing, got %d", code)
+	}
+}
+
+func TestCreateBasic(t *testing.T) {
+	store := newMockStorage()
+
+	var buf bytes.Buffer
+	code := HandleTask([]string{"create", "--subject=New task"}, &buf, store)
+	if code != 0 {
+		t.Errorf("expected exit 0, got %d", code)
+	}
+	out := buf.String()
+	if !strings.Contains(out, "task ") {
+		t.Errorf("expected 'task <id>' in output, got:\n%s", out)
+	}
+	// Verify task was stored
+	if len(store.list.Tasks) != 1 {
+		t.Fatalf("expected 1 task created, got %d", len(store.list.Tasks))
+	}
+	if store.list.Tasks[0].Subject != "New task" {
+		t.Errorf("expected subject 'New task', got %q", store.list.Tasks[0].Subject)
+	}
+	if store.list.Tasks[0].Status != StatusPending {
+		t.Errorf("expected default status pending, got %q", store.list.Tasks[0].Status)
+	}
+}
+
+func TestCreateWithPhaseName(t *testing.T) {
+	store := newMockStorage()
+
+	var buf bytes.Buffer
+	code := HandleTask([]string{"create", "--subject=Task", "--phase-name=My Phase"}, &buf, store)
+	if code != 0 {
+		t.Errorf("expected exit 0, got %d", code)
+	}
+	out := buf.String()
+	// Should output phase <id> and task <id>
+	if !strings.Contains(out, "phase ") {
+		t.Errorf("expected 'phase <id>' in output, got:\n%s", out)
+	}
+	if !strings.Contains(out, "task ") {
+		t.Errorf("expected 'task <id>' in output, got:\n%s", out)
+	}
+	// Verify phase was created
+	if len(store.list.Phases) != 1 {
+		t.Fatalf("expected 1 phase created, got %d", len(store.list.Phases))
+	}
+	if store.list.Phases[0].Name != "My Phase" {
+		t.Errorf("expected phase name 'My Phase', got %q", store.list.Phases[0].Name)
+	}
+}
+
+func TestCreateWithPhaseAndSectionName(t *testing.T) {
+	store := newMockStorage()
+
+	var buf bytes.Buffer
+	code := HandleTask([]string{"create", "--subject=Task", "--phase-name=Phase 1", "--section-name=Section 1.1"}, &buf, store)
+	if code != 0 {
+		t.Errorf("expected exit 0, got %d", code)
+	}
+	out := buf.String()
+	if !strings.Contains(out, "phase ") {
+		t.Errorf("expected 'phase <id>' in output, got:\n%s", out)
+	}
+	if !strings.Contains(out, "section ") {
+		t.Errorf("expected 'section <id>' in output, got:\n%s", out)
+	}
+	if !strings.Contains(out, "task ") {
+		t.Errorf("expected 'task <id>' in output, got:\n%s", out)
+	}
+}
+
+func TestCreateWithExistingPhase(t *testing.T) {
+	store := newMockStorage()
+	store.list.Phases = []Phase{{ID: "phase001", Name: "Existing Phase"}}
+
+	var buf bytes.Buffer
+	code := HandleTask([]string{"create", "--subject=Task", "--phase=phase001"}, &buf, store)
+	if code != 0 {
+		t.Errorf("expected exit 0, got %d", code)
+	}
+	out := buf.String()
+	// Should NOT output phase <id> since we didn't create a new one
+	if strings.Contains(out, "phase ") {
+		t.Errorf("expected no 'phase <id>' when using existing phase, got:\n%s", out)
+	}
+	if !strings.Contains(out, "task ") {
+		t.Errorf("expected 'task <id>' in output, got:\n%s", out)
+	}
+	if len(store.list.Tasks) > 0 && store.list.Tasks[0].PhaseID != "phase001" {
+		t.Errorf("expected task phaseID 'phase001', got %q", store.list.Tasks[0].PhaseID)
+	}
+}
+
+func TestCreateInvalidStatus(t *testing.T) {
+	store := newMockStorage()
+
+	var buf bytes.Buffer
+	code := HandleTask([]string{"create", "--subject=Task", "--status=invalid"}, &buf, store)
+	if code != 1 {
+		t.Errorf("expected exit 1 for invalid status, got %d", code)
+	}
+}
+
+func TestCreateWithProjectNameAndDescription(t *testing.T) {
+	store := newMockStorage()
+
+	var buf bytes.Buffer
+	code := HandleTask([]string{"create", "--subject=Task", "--project-name=My Project", "--project-description=A great project"}, &buf, store)
+	if code != 0 {
+		t.Errorf("expected exit 0, got %d", code)
+	}
+	if store.list.Name != "My Project" {
+		t.Errorf("expected project name 'My Project', got %q", store.list.Name)
+	}
+	if store.list.Description != "A great project" {
+		t.Errorf("expected project description 'A great project', got %q", store.list.Description)
+	}
+}
+
+func TestCreateWithStatus(t *testing.T) {
+	store := newMockStorage()
+
+	var buf bytes.Buffer
+	code := HandleTask([]string{"create", "--subject=Task", "--status=in_progress"}, &buf, store)
+	if code != 0 {
+		t.Errorf("expected exit 0, got %d", code)
+	}
+	if len(store.list.Tasks) != 1 {
+		t.Fatalf("expected 1 task created, got %d", len(store.list.Tasks))
+	}
+	if store.list.Tasks[0].Status != StatusInProgress {
+		t.Errorf("expected status in_progress, got %q", store.list.Tasks[0].Status)
+	}
+}
+
+func TestCreateWithExistingSection(t *testing.T) {
+	store := newMockStorage()
+	store.list.Phases = []Phase{{ID: "phase001", Name: "Phase 1"}}
+	store.list.Sections = []Section{{ID: "sect0001", PhaseID: "phase001", Name: "Section 1.1"}}
+
+	var buf bytes.Buffer
+	code := HandleTask([]string{"create", "--subject=Task", "--phase=phase001", "--section=sect0001"}, &buf, store)
+	if code != 0 {
+		t.Errorf("expected exit 0, got %d", code)
+	}
+	out := buf.String()
+	// Should NOT output "section <id>" since we used an existing section
+	if strings.Contains(out, "section ") {
+		t.Errorf("expected no 'section <id>' when using existing section, got:\n%s", out)
+	}
+	if !strings.Contains(out, "task ") {
+		t.Errorf("expected 'task <id>' in output, got:\n%s", out)
+	}
+	if len(store.list.Tasks) != 1 || store.list.Tasks[0].SectionID != "sect0001" {
+		t.Errorf("expected task sectionID 'sect0001', tasks: %+v", store.list.Tasks)
+	}
+	// No new section should have been created
+	if len(store.list.Sections) != 1 {
+		t.Errorf("expected existing section count to remain 1, got %d", len(store.list.Sections))
+	}
+}
+
+func TestCreatePhaseDescription(t *testing.T) {
+	store := newMockStorage()
+
+	var buf bytes.Buffer
+	code := HandleTask([]string{"create", "--subject=Task", "--phase-name=My Phase", "--phase-description=Phase desc"}, &buf, store)
+	if code != 0 {
+		t.Errorf("expected exit 0, got %d", code)
+	}
+	if len(store.list.Phases) != 1 {
+		t.Fatalf("expected 1 phase created, got %d", len(store.list.Phases))
+	}
+	if store.list.Phases[0].Description != "Phase desc" {
+		t.Errorf("expected phase description 'Phase desc', got %q", store.list.Phases[0].Description)
+	}
+}
+
+func TestCreateSectionDescription(t *testing.T) {
+	store := newMockStorage()
+
+	var buf bytes.Buffer
+	code := HandleTask([]string{"create", "--subject=Task", "--phase-name=Phase 1", "--section-name=Section 1.1", "--section-description=Section desc"}, &buf, store)
+	if code != 0 {
+		t.Errorf("expected exit 0, got %d", code)
+	}
+	if len(store.list.Sections) != 1 {
+		t.Fatalf("expected 1 section created, got %d", len(store.list.Sections))
+	}
+	if store.list.Sections[0].Description != "Section desc" {
+		t.Errorf("expected section description 'Section desc', got %q", store.list.Sections[0].Description)
+	}
+}
+
+func TestCreateSectionPhaseIDAssigned(t *testing.T) {
+	store := newMockStorage()
+
+	var buf bytes.Buffer
+	code := HandleTask([]string{"create", "--subject=Task", "--phase-name=Phase 1", "--section-name=Section 1.1"}, &buf, store)
+	if code != 0 {
+		t.Errorf("expected exit 0, got %d", code)
+	}
+	if len(store.list.Phases) != 1 {
+		t.Fatalf("expected 1 phase, got %d", len(store.list.Phases))
+	}
+	if len(store.list.Sections) != 1 {
+		t.Fatalf("expected 1 section, got %d", len(store.list.Sections))
+	}
+	// Section must reference the auto-generated phase's ID.
+	if store.list.Sections[0].PhaseID != store.list.Phases[0].ID {
+		t.Errorf("expected section PhaseID %q, got %q", store.list.Phases[0].ID, store.list.Sections[0].PhaseID)
+	}
+}
+
+func TestCreateOutputOrdering(t *testing.T) {
+	store := newMockStorage()
+
+	var buf bytes.Buffer
+	code := HandleTask([]string{"create", "--subject=Task", "--phase-name=Phase 1", "--section-name=Section 1.1"}, &buf, store)
+	if code != 0 {
+		t.Errorf("expected exit 0, got %d", code)
+	}
+	out := buf.String()
+	lines := strings.Split(strings.TrimSpace(out), "\n")
+	if len(lines) != 3 {
+		t.Fatalf("expected 3 output lines (phase, section, task), got %d: %q", len(lines), out)
+	}
+	if !strings.HasPrefix(lines[0], "phase ") {
+		t.Errorf("expected first line to start with 'phase ', got %q", lines[0])
+	}
+	if !strings.HasPrefix(lines[1], "section ") {
+		t.Errorf("expected second line to start with 'section ', got %q", lines[1])
+	}
+	if !strings.HasPrefix(lines[2], "task ") {
+		t.Errorf("expected third line to start with 'task ', got %q", lines[2])
+	}
+}
+
+func TestCreateSectionNameWithoutPhaseContext(t *testing.T) {
+	store := newMockStorage()
+
+	var buf bytes.Buffer
+	// --section-name without --phase or --phase-name should return 1
+	code := HandleTask([]string{"create", "--subject=Task", "--section-name=Section 1.1"}, &buf, store)
+	if code != 1 {
+		t.Errorf("expected exit 1 when --section-name used without phase context, got %d", code)
+	}
+}
+
+func TestCreateSectionWithoutPhaseContext(t *testing.T) {
+	store := newMockStorage()
+	store.list.Sections = []Section{{ID: "sect0001", PhaseID: "phase001", Name: "Section 1.1"}}
+
+	var buf bytes.Buffer
+	// --section without --phase or --phase-name should return 1
+	code := HandleTask([]string{"create", "--subject=Task", "--section=sect0001"}, &buf, store)
+	if code != 1 {
+		t.Errorf("expected exit 1 when --section used without phase context, got %d", code)
+	}
+}
+
+// --- update tests ---
+
+func TestUpdateStatus(t *testing.T) {
+	store := newMockStorage()
+	now := time.Now()
+	task := &Task{ID: "upd00001", Subject: "Update me", Status: StatusPending, LastUpdated: now}
+	store.tasks["upd00001"] = task
+	store.list.Tasks = []Task{*task}
+
+	var buf bytes.Buffer
+	code := HandleTask([]string{"update", "upd00001", "--status=in_progress"}, &buf, store)
+	if code != 0 {
+		t.Errorf("expected exit 0, got %d", code)
+	}
+	if store.tasks["upd00001"].Status != StatusInProgress {
+		t.Errorf("expected status in_progress, got %q", store.tasks["upd00001"].Status)
+	}
+}
+
+func TestUpdateNotes(t *testing.T) {
+	store := newMockStorage()
+	now := time.Now()
+	task := &Task{ID: "upd00002", Subject: "Notes task", Status: StatusPending, LastUpdated: now}
+	store.tasks["upd00002"] = task
+	store.list.Tasks = []Task{*task}
+
+	var buf bytes.Buffer
+	code := HandleTask([]string{"update", "upd00002", "--notes=Some notes here"}, &buf, store)
+	if code != 0 {
+		t.Errorf("expected exit 0, got %d", code)
+	}
+	if store.tasks["upd00002"].Notes != "Some notes here" {
+		t.Errorf("expected notes 'Some notes here', got %q", store.tasks["upd00002"].Notes)
+	}
+}
+
+func TestUpdateCmdNotFound(t *testing.T) {
+	store := newMockStorage()
+
+	var buf bytes.Buffer
+	code := HandleTask([]string{"update", "notexist", "--status=completed"}, &buf, store)
+	if code != 1 {
+		t.Errorf("expected exit 1 for missing task, got %d", code)
+	}
+}
+
+func TestUpdateMissingID(t *testing.T) {
+	store := newMockStorage()
+
+	var buf bytes.Buffer
+	code := HandleTask([]string{"update"}, &buf, store)
+	if code != 1 {
+		t.Errorf("expected exit 1 when ID not provided, got %d", code)
+	}
+}
+
+func TestUpdatePartialPreservesFields(t *testing.T) {
+	store := newMockStorage()
+	now := time.Now()
+	task := &Task{ID: "upd00003", Subject: "Keep me", Status: StatusPending, Notes: "keep notes", LastUpdated: now}
+	store.tasks["upd00003"] = task
+	store.list.Tasks = []Task{*task}
+
+	var buf bytes.Buffer
+	code := HandleTask([]string{"update", "upd00003", "--status=completed"}, &buf, store)
+	if code != 0 {
+		t.Errorf("expected exit 0, got %d", code)
+	}
+	updated := store.tasks["upd00003"]
+	if updated.Subject != "Keep me" {
+		t.Errorf("expected subject to be preserved, got %q", updated.Subject)
+	}
+	if updated.Notes != "keep notes" {
+		t.Errorf("expected notes to be preserved, got %q", updated.Notes)
+	}
+	if updated.Status != StatusCompleted {
+		t.Errorf("expected status completed, got %q", updated.Status)
+	}
+}
+
+func TestUpdateInvalidStatus(t *testing.T) {
+	store := newMockStorage()
+	now := time.Now()
+	task := &Task{ID: "upd00004", Subject: "Task", Status: StatusPending, LastUpdated: now}
+	store.tasks["upd00004"] = task
+	store.list.Tasks = []Task{*task}
+
+	var buf bytes.Buffer
+	code := HandleTask([]string{"update", "upd00004", "--status=bad"}, &buf, store)
+	if code != 1 {
+		t.Errorf("expected exit 1 for invalid status, got %d", code)
+	}
+}
+
+func TestUpdateSetsLastUpdated(t *testing.T) {
+	store := newMockStorage()
+	past := time.Now().Add(-1 * time.Hour)
+	task := &Task{ID: "upd00005", Subject: "Time task", Status: StatusPending, LastUpdated: past}
+	store.tasks["upd00005"] = task
+	store.list.Tasks = []Task{*task}
+
+	var buf bytes.Buffer
+	code := HandleTask([]string{"update", "upd00005", "--status=completed"}, &buf, store)
+	if code != 0 {
+		t.Errorf("expected exit 0, got %d", code)
+	}
+	updated := store.tasks["upd00005"]
+	if !updated.LastUpdated.After(past) {
+		t.Errorf("expected LastUpdated to be updated, old=%v new=%v", past, updated.LastUpdated)
+	}
+}
+
+func TestUpdateSubject(t *testing.T) {
+	store := newMockStorage()
+	now := time.Now()
+	task := &Task{ID: "upd00006", Subject: "Old subject", Status: StatusPending, LastUpdated: now}
+	store.tasks["upd00006"] = task
+	store.list.Tasks = []Task{*task}
+
+	var buf bytes.Buffer
+	code := HandleTask([]string{"update", "upd00006", "--subject=New subject"}, &buf, store)
+	if code != 0 {
+		t.Errorf("expected exit 0, got %d", code)
+	}
+	if store.tasks["upd00006"].Subject != "New subject" {
+		t.Errorf("expected subject 'New subject', got %q", store.tasks["upd00006"].Subject)
+	}
+}
+
+func TestUpdateSubjectClear(t *testing.T) {
+	store := newMockStorage()
+	now := time.Now()
+	task := &Task{ID: "upd00007", Subject: "Has subject", Status: StatusPending, LastUpdated: now}
+	store.tasks["upd00007"] = task
+	store.list.Tasks = []Task{*task}
+
+	var buf bytes.Buffer
+	// --subject="" should clear the subject (not treated as "not provided")
+	code := HandleTask([]string{"update", "upd00007", "--subject="}, &buf, store)
+	if code != 0 {
+		t.Errorf("expected exit 0, got %d", code)
+	}
+	if store.tasks["upd00007"].Subject != "" {
+		t.Errorf("expected subject to be cleared, got %q", store.tasks["upd00007"].Subject)
+	}
+}
+
+// --- update metadata tests ---
+
+func TestUpdatePhaseReassigns(t *testing.T) {
+	store := newMockStorage()
+	now := time.Now()
+	task := &Task{ID: "upd00010", Subject: "Task", Status: StatusPending, LastUpdated: now}
+	store.tasks["upd00010"] = task
+	store.list.Tasks = []Task{*task}
+	store.list.Phases = []Phase{{ID: "phase001", Name: "Phase 1"}}
+
+	var buf bytes.Buffer
+	code := HandleTask([]string{"update", "upd00010", "--phase=phase001"}, &buf, store)
+	if code != 0 {
+		t.Errorf("expected exit 0, got %d", code)
+	}
+	if store.tasks["upd00010"].PhaseID != "phase001" {
+		t.Errorf("expected phaseID 'phase001', got %q", store.tasks["upd00010"].PhaseID)
+	}
+}
+
+func TestUpdatePhaseNameUpserts(t *testing.T) {
+	store := newMockStorage()
+	now := time.Now()
+	task := &Task{ID: "upd00011", Subject: "Task", Status: StatusPending, PhaseID: "phase001", LastUpdated: now}
+	store.tasks["upd00011"] = task
+	store.list.Tasks = []Task{*task}
+	store.list.Phases = []Phase{{ID: "phase001", Name: "Old Name"}}
+
+	var buf bytes.Buffer
+	code := HandleTask([]string{"update", "upd00011", "--phase=phase001", "--phase-name=New Name"}, &buf, store)
+	if code != 0 {
+		t.Errorf("expected exit 0, got %d", code)
+	}
+	if store.list.Phases[0].Name != "New Name" {
+		t.Errorf("expected phase name 'New Name', got %q", store.list.Phases[0].Name)
+	}
+}
+
+func TestUpdatePhaseDescriptionUpserts(t *testing.T) {
+	store := newMockStorage()
+	now := time.Now()
+	task := &Task{ID: "upd00012", Subject: "Task", Status: StatusPending, PhaseID: "phase001", LastUpdated: now}
+	store.tasks["upd00012"] = task
+	store.list.Tasks = []Task{*task}
+	store.list.Phases = []Phase{{ID: "phase001", Name: "Phase 1"}}
+
+	var buf bytes.Buffer
+	code := HandleTask([]string{"update", "upd00012", "--phase=phase001", "--phase-description=Phase desc"}, &buf, store)
+	if code != 0 {
+		t.Errorf("expected exit 0, got %d", code)
+	}
+	if store.list.Phases[0].Description != "Phase desc" {
+		t.Errorf("expected phase description 'Phase desc', got %q", store.list.Phases[0].Description)
+	}
+}
+
+func TestUpdateSectionReassigns(t *testing.T) {
+	store := newMockStorage()
+	now := time.Now()
+	task := &Task{ID: "upd00013", Subject: "Task", Status: StatusPending, PhaseID: "phase001", LastUpdated: now}
+	store.tasks["upd00013"] = task
+	store.list.Tasks = []Task{*task}
+	store.list.Phases = []Phase{{ID: "phase001", Name: "Phase 1"}}
+	store.list.Sections = []Section{{ID: "sect0001", PhaseID: "phase001", Name: "Section 1"}}
+
+	var buf bytes.Buffer
+	code := HandleTask([]string{"update", "upd00013", "--phase=phase001", "--section=sect0001"}, &buf, store)
+	if code != 0 {
+		t.Errorf("expected exit 0, got %d", code)
+	}
+	if store.tasks["upd00013"].SectionID != "sect0001" {
+		t.Errorf("expected sectionID 'sect0001', got %q", store.tasks["upd00013"].SectionID)
+	}
+}
+
+func TestUpdateSectionNameUpserts(t *testing.T) {
+	store := newMockStorage()
+	now := time.Now()
+	task := &Task{ID: "upd00014", Subject: "Task", Status: StatusPending, PhaseID: "phase001", SectionID: "sect0001", LastUpdated: now}
+	store.tasks["upd00014"] = task
+	store.list.Tasks = []Task{*task}
+	store.list.Phases = []Phase{{ID: "phase001", Name: "Phase 1"}}
+	store.list.Sections = []Section{{ID: "sect0001", PhaseID: "phase001", Name: "Old Section"}}
+
+	var buf bytes.Buffer
+	code := HandleTask([]string{"update", "upd00014", "--phase=phase001", "--section=sect0001", "--section-name=New Section"}, &buf, store)
+	if code != 0 {
+		t.Errorf("expected exit 0, got %d", code)
+	}
+	if store.list.Sections[0].Name != "New Section" {
+		t.Errorf("expected section name 'New Section', got %q", store.list.Sections[0].Name)
+	}
+}
+
+func TestUpdateSectionDescriptionUpserts(t *testing.T) {
+	store := newMockStorage()
+	now := time.Now()
+	task := &Task{ID: "upd00015", Subject: "Task", Status: StatusPending, PhaseID: "phase001", SectionID: "sect0001", LastUpdated: now}
+	store.tasks["upd00015"] = task
+	store.list.Tasks = []Task{*task}
+	store.list.Phases = []Phase{{ID: "phase001", Name: "Phase 1"}}
+	store.list.Sections = []Section{{ID: "sect0001", PhaseID: "phase001", Name: "Section 1"}}
+
+	var buf bytes.Buffer
+	code := HandleTask([]string{"update", "upd00015", "--phase=phase001", "--section=sect0001", "--section-description=Section desc"}, &buf, store)
+	if code != 0 {
+		t.Errorf("expected exit 0, got %d", code)
+	}
+	if store.list.Sections[0].Description != "Section desc" {
+		t.Errorf("expected section description 'Section desc', got %q", store.list.Sections[0].Description)
+	}
+}
+
+func TestUpdateProjectMetadata(t *testing.T) {
+	store := newMockStorage()
+	now := time.Now()
+	task := &Task{ID: "upd00016", Subject: "Task", Status: StatusPending, LastUpdated: now}
+	store.tasks["upd00016"] = task
+	store.list.Tasks = []Task{*task}
+
+	var buf bytes.Buffer
+	code := HandleTask([]string{"update", "upd00016", "--project-name=My Project", "--project-description=A description"}, &buf, store)
+	if code != 0 {
+		t.Errorf("expected exit 0, got %d", code)
+	}
+	if store.list.Name != "My Project" {
+		t.Errorf("expected project name 'My Project', got %q", store.list.Name)
+	}
+	if store.list.Description != "A description" {
+		t.Errorf("expected project description 'A description', got %q", store.list.Description)
+	}
+}
+
+func TestUpdatePhaseNameRequiresPhase(t *testing.T) {
+	store := newMockStorage()
+	now := time.Now()
+	task := &Task{ID: "upd00017", Subject: "Task", Status: StatusPending, LastUpdated: now}
+	store.tasks["upd00017"] = task
+	store.list.Tasks = []Task{*task}
+
+	var buf bytes.Buffer
+	// --phase-name without --phase should return 1
+	code := HandleTask([]string{"update", "upd00017", "--phase-name=Some Phase"}, &buf, store)
+	if code != 1 {
+		t.Errorf("expected exit 1 when --phase-name used without --phase, got %d", code)
+	}
+}
+
+func TestUpdatePhaseDescriptionRequiresPhase(t *testing.T) {
+	store := newMockStorage()
+	now := time.Now()
+	task := &Task{ID: "upd00018", Subject: "Task", Status: StatusPending, LastUpdated: now}
+	store.tasks["upd00018"] = task
+	store.list.Tasks = []Task{*task}
+
+	var buf bytes.Buffer
+	// --phase-description without --phase should return 1
+	code := HandleTask([]string{"update", "upd00018", "--phase-description=Some desc"}, &buf, store)
+	if code != 1 {
+		t.Errorf("expected exit 1 when --phase-description used without --phase, got %d", code)
+	}
+}
+
+func TestUpdateSectionRequiresPhase(t *testing.T) {
+	store := newMockStorage()
+	now := time.Now()
+	task := &Task{ID: "upd00019", Subject: "Task", Status: StatusPending, LastUpdated: now}
+	store.tasks["upd00019"] = task
+	store.list.Tasks = []Task{*task}
+	store.list.Sections = []Section{{ID: "sect0001", PhaseID: "phase001", Name: "Section 1"}}
+
+	var buf bytes.Buffer
+	// --section without --phase should return 1
+	code := HandleTask([]string{"update", "upd00019", "--section=sect0001"}, &buf, store)
+	if code != 1 {
+		t.Errorf("expected exit 1 when --section used without --phase, got %d", code)
+	}
+}
+
+func TestUpdateSectionNameRequiresSection(t *testing.T) {
+	store := newMockStorage()
+	now := time.Now()
+	task := &Task{ID: "upd00020", Subject: "Task", Status: StatusPending, PhaseID: "phase001", LastUpdated: now}
+	store.tasks["upd00020"] = task
+	store.list.Tasks = []Task{*task}
+	store.list.Phases = []Phase{{ID: "phase001", Name: "Phase 1"}}
+
+	var buf bytes.Buffer
+	// --section-name without --section should return 1
+	code := HandleTask([]string{"update", "upd00020", "--phase=phase001", "--section-name=Some Section"}, &buf, store)
+	if code != 1 {
+		t.Errorf("expected exit 1 when --section-name used without --section, got %d", code)
+	}
+}
+
+func TestUpdateSectionDescriptionRequiresSection(t *testing.T) {
+	store := newMockStorage()
+	now := time.Now()
+	task := &Task{ID: "upd00021", Subject: "Task", Status: StatusPending, PhaseID: "phase001", LastUpdated: now}
+	store.tasks["upd00021"] = task
+	store.list.Tasks = []Task{*task}
+	store.list.Phases = []Phase{{ID: "phase001", Name: "Phase 1"}}
+
+	var buf bytes.Buffer
+	// --section-description without --section should return 1
+	code := HandleTask([]string{"update", "upd00021", "--phase=phase001", "--section-description=Some desc"}, &buf, store)
+	if code != 1 {
+		t.Errorf("expected exit 1 when --section-description used without --section, got %d", code)
+	}
+}
+
+// --- delete tests ---
+
+func TestDeleteByID(t *testing.T) {
+	store := newMockStorage()
+	now := time.Now()
+	task := &Task{ID: "del00001", Subject: "Delete me", Status: StatusPending, LastUpdated: now}
+	store.tasks["del00001"] = task
+	store.list.Tasks = []Task{*task}
+
+	var buf bytes.Buffer
+	code := HandleTask([]string{"delete", "del00001"}, &buf, store)
+	if code != 0 {
+		t.Errorf("expected exit 0, got %d", code)
+	}
+	if buf.Len() > 0 {
+		t.Errorf("expected no output on successful delete, got:\n%s", buf.String())
+	}
+	if _, err := store.Get("del00001"); err == nil {
+		t.Errorf("expected task to be deleted, but it still exists")
+	}
+}
+
+func TestDeleteCmdNotFound(t *testing.T) {
+	store := newMockStorage()
+
+	var buf bytes.Buffer
+	code := HandleTask([]string{"delete", "notexist"}, &buf, store)
+	if code != 1 {
+		t.Errorf("expected exit 1 for missing task, got %d", code)
+	}
+}
+
+func TestDeleteMissingID(t *testing.T) {
+	store := newMockStorage()
+
+	var buf bytes.Buffer
+	code := HandleTask([]string{"delete"}, &buf, store)
+	if code != 1 {
+		t.Errorf("expected exit 1 when ID not provided, got %d", code)
+	}
+}
+
+// --- export tests ---
+
+func TestExportBasic(t *testing.T) {
+	store := newMockStorage()
+	now := time.Now()
+	store.list.Name = "My Project"
+	store.list.Tasks = []Task{
+		{ID: "exp00001", Subject: "Export task", Status: StatusPending, LastUpdated: now},
+	}
+
+	var buf bytes.Buffer
+	code := HandleTask([]string{"export"}, &buf, store)
+	if code != 0 {
+		t.Errorf("expected exit 0, got %d", code)
+	}
+	out := buf.String()
+	if !strings.Contains(out, "My Project") {
+		t.Errorf("expected project name in export output, got:\n%s", out)
+	}
+	if !strings.Contains(out, "exp00001") {
+		t.Errorf("expected task ID in export output, got:\n%s", out)
+	}
+}
+
+func TestExportStatusFilter(t *testing.T) {
+	store := newMockStorage()
+	now := time.Now()
+	store.list.Tasks = []Task{
+		{ID: "exp00001", Subject: "Pending task", Status: StatusPending, LastUpdated: now},
+		{ID: "exp00002", Subject: "Completed task", Status: StatusCompleted, LastUpdated: now},
+	}
+
+	var buf bytes.Buffer
+	code := HandleTask([]string{"export", "--status=pending"}, &buf, store)
+	if code != 0 {
+		t.Errorf("expected exit 0, got %d", code)
+	}
+	out := buf.String()
+	if !strings.Contains(out, "exp00001") {
+		t.Errorf("expected pending task in export")
+	}
+	if strings.Contains(out, "exp00002") {
+		t.Errorf("expected completed task to be filtered out of export")
+	}
+}
+
+func TestExportToFile(t *testing.T) {
+	store := newMockStorage()
+	now := time.Now()
+	store.list.Tasks = []Task{
+		{ID: "exp00001", Subject: "File export task", Status: StatusPending, LastUpdated: now},
+	}
+
+	outFile := t.TempDir() + "/export.md"
+	var buf bytes.Buffer
+	code := HandleTask([]string{"export", "--output=" + outFile}, &buf, store)
+	if code != 0 {
+		t.Errorf("expected exit 0, got %d", code)
+	}
+	// buf should be empty (written to file instead)
+	if buf.Len() > 0 {
+		t.Errorf("expected nothing written to stdout when --output given, got:\n%s", buf.String())
+	}
+}
+
+func TestExportStatusRepeatable(t *testing.T) {
+	store := newMockStorage()
+	now := time.Now()
+	store.list.Tasks = []Task{
+		{ID: "exp00001", Subject: "Pending task", Status: StatusPending, LastUpdated: now},
+		{ID: "exp00002", Subject: "In progress task", Status: StatusInProgress, LastUpdated: now},
+		{ID: "exp00003", Subject: "Completed task", Status: StatusCompleted, LastUpdated: now},
+	}
+
+	var buf bytes.Buffer
+	code := HandleTask([]string{"export", "--status=pending", "--status=in_progress"}, &buf, store)
+	if code != 0 {
+		t.Errorf("expected exit 0, got %d", code)
+	}
+	out := buf.String()
+	if !strings.Contains(out, "exp00001") {
+		t.Errorf("expected pending task in export")
+	}
+	if !strings.Contains(out, "exp00002") {
+		t.Errorf("expected in_progress task in export")
+	}
+	if strings.Contains(out, "exp00003") {
+		t.Errorf("expected completed task to be filtered out")
+	}
+}
+
+func TestExportPhaseAndSectionDescriptions(t *testing.T) {
+	store := newMockStorage()
+	now := time.Now()
+	store.list.Name = "Export Project"
+	store.list.Phases = []Phase{
+		{ID: "ph000001", Name: "Phase One", Description: "Phase one goals"},
+	}
+	store.list.Sections = []Section{
+		{ID: "sec00001", PhaseID: "ph000001", Name: "Section One", Description: "Section one context"},
+	}
+	store.list.Tasks = []Task{
+		{ID: "exp00001", Subject: "Task in section", Status: StatusPending, PhaseID: "ph000001", SectionID: "sec00001", LastUpdated: now},
+	}
+
+	var buf bytes.Buffer
+	code := HandleTask([]string{"export"}, &buf, store)
+	if code != 0 {
+		t.Errorf("expected exit 0, got %d", code)
+	}
+	out := buf.String()
+	// Project H1
+	if !strings.Contains(out, "# Export Project") {
+		t.Errorf("expected project H1 in export output, got:\n%s", out)
+	}
+	// Phase description
+	if !strings.Contains(out, "Phase one goals") {
+		t.Errorf("expected phase description in export output, got:\n%s", out)
+	}
+	// Section description
+	if !strings.Contains(out, "Section one context") {
+		t.Errorf("expected section description in export output, got:\n%s", out)
+	}
+}
diff --git a/internal/task/format.go b/internal/task/format.go
new file mode 100644
index 0000000..4ba131a
--- /dev/null
+++ b/internal/task/format.go
@@ -0,0 +1,234 @@
+package task
+
+import (
+	"encoding/json"
+	"fmt"
+	"sort"
+	"strings"
+)
+
+// FormatTaskMarkdown returns a single-task markdown string for the get subcommand.
+func FormatTaskMarkdown(task *Task, list *TaskList) string {
+	var sb strings.Builder
+	fmt.Fprintf(&sb, "# %s\n\n", task.Subject)
+	fmt.Fprintf(&sb, "**Status:** %s\n", task.Status)
+	if task.PhaseID != "" {
+		fmt.Fprintf(&sb, "**Phase:** %s\n", resolvePhaseName(task.PhaseID, list))
+	}
+	if task.SectionID != "" {
+		fmt.Fprintf(&sb, "**Section:** %s\n", resolveSectionName(task.SectionID, list))
+	}
+	fmt.Fprintf(&sb, "**Updated:** %s\n", task.LastUpdated.UTC().Format("2006-01-02T15:04:05Z"))
+	sb.WriteString("\n")
+	if task.Notes != "" {
+		fmt.Fprintf(&sb, "%s\n", task.Notes)
+	} else {
+		sb.WriteString("**Notes:** (none)\n")
+	}
+	return sb.String()
+}
+
+// FormatTaskJSON returns a single task as indented JSON (not wrapped in an envelope).
+func FormatTaskJSON(task *Task) (string, error) {
+	b, err := json.MarshalIndent(task, "", "  ")
+	if err != nil {
+		return "", err
+	}
+	return string(b), nil
+}
+
+// FormatListMarkdown returns tasks grouped by phase/section as markdown.
+// When flat is true, headings and notes are suppressed.
+func FormatListMarkdown(tasks []Task, list *TaskList, flat bool) string {
+	if flat {
+		return renderFlatList(tasks)
+	}
+	return renderGrouped(tasks, list, false)
+}
+
+// FormatListJSON returns tasks wrapped in a {"tasks": [...]} JSON envelope.
+func FormatListJSON(tasks []Task) (string, error) {
+	envelope := struct {
+		Tasks []Task `json:"tasks"`
+	}{Tasks: tasks}
+	b, err := json.MarshalIndent(envelope, "", "  ")
+	if err != nil {
+		return "", err
+	}
+	return string(b), nil
+}
+
+// FormatExportMarkdown returns tasks as markdown with project name H1 and description.
+func FormatExportMarkdown(tasks []Task, list *TaskList) string {
+	var sb strings.Builder
+	if list.Name != "" {
+		fmt.Fprintf(&sb, "# %s\n\n", list.Name)
+		if list.Description != "" {
+			fmt.Fprintf(&sb, "%s\n\n", list.Description)
+		}
+	}
+	sb.WriteString(renderGrouped(tasks, list, true))
+	return sb.String()
+}
+
+// resolvePhaseName returns the phase name for the given ID, or the ID itself as fallback.
+func resolvePhaseName(phaseID string, list *TaskList) string {
+	for _, p := range list.Phases {
+		if p.ID == phaseID {
+			if p.Name != "" {
+				return p.Name
+			}
+			return p.ID
+		}
+	}
+	return phaseID
+}
+
+// resolveSectionName returns the section name for the given ID, or the ID itself as fallback.
+func resolveSectionName(sectionID string, list *TaskList) string {
+	for _, s := range list.Sections {
+		if s.ID == sectionID {
+			if s.Name != "" {
+				return s.Name
+			}
+			return s.ID
+		}
+	}
+	return sectionID
+}
+
+// taskBullet returns the markdown bullet line for a task.
+func taskBullet(t Task) string {
+	return fmt.Sprintf("- `%s` [%s] %s", t.ID, t.Status, t.Subject)
+}
+
+// notesBlock returns a 2-space-indented fenced notes block.
+func notesBlock(notes string) string {
+	var sb strings.Builder
+	sb.WriteString("\n  ```notes\n")
+	for _, line := range strings.Split(notes, "\n") {
+		fmt.Fprintf(&sb, "  %s\n", line)
+	}
+	sb.WriteString("  ```\n")
+	return sb.String()
+}
+
+// renderFlatList renders tasks as a flat bullet list with no headings or notes.
+func renderFlatList(tasks []Task) string {
+	var sb strings.Builder
+	for _, t := range tasks {
+		fmt.Fprintf(&sb, "%s\n", taskBullet(t))
+	}
+	return sb.String()
+}
+
+// renderGrouped renders tasks grouped by phase then section.
+// includePhaseDesc controls whether phase descriptions are printed (used by export).
+func renderGrouped(tasks []Task, list *TaskList, includePhaseDesc bool) string {
+	var sb strings.Builder
+
+	// Build a lookup: phaseID -> []Task, sectionID -> []Task
+	byPhase := make(map[string][]Task)
+	bySection := make(map[string][]Task)
+	for _, t := range tasks {
+		if t.PhaseID == "" {
+			byPhase[""] = append(byPhase[""], t)
+		} else if t.SectionID == "" {
+			byPhase[t.PhaseID] = append(byPhase[t.PhaseID], t)
+		} else {
+			bySection[t.SectionID] = append(bySection[t.SectionID], t)
+		}
+	}
+
+	// Track which phase IDs are covered by list.Phases.
+	knownPhaseIDs := make(map[string]bool)
+	for _, p := range list.Phases {
+		knownPhaseIDs[p.ID] = true
+	}
+
+	// Render phases in TaskList order
+	for _, phase := range list.Phases {
+		// Determine if this phase has any tasks (direct or via sections)
+		hasAny := len(byPhase[phase.ID]) > 0
+		if !hasAny {
+			for _, sec := range list.Sections {
+				if sec.PhaseID == phase.ID && len(bySection[sec.ID]) > 0 {
+					hasAny = true
+					break
+				}
+			}
+		}
+		if !hasAny {
+			continue
+		}
+
+		fmt.Fprintf(&sb, "## %s\n\n", resolvePhaseName(phase.ID, list))
+		if includePhaseDesc && phase.Description != "" {
+			fmt.Fprintf(&sb, "%s\n\n", phase.Description)
+		}
+
+		// Direct phase tasks (no section)
+		for _, t := range byPhase[phase.ID] {
+			sb.WriteString(taskBullet(t))
+			sb.WriteString("\n")
+			if t.Notes != "" {
+				sb.WriteString(notesBlock(t.Notes))
+			}
+		}
+
+		// Sections in TaskList order
+		for _, sec := range list.Sections {
+			if sec.PhaseID != phase.ID {
+				continue
+			}
+			secTasks := bySection[sec.ID]
+			if len(secTasks) == 0 {
+				continue
+			}
+			fmt.Fprintf(&sb, "### %s\n\n", resolveSectionName(sec.ID, list))
+			if includePhaseDesc && sec.Description != "" {
+				fmt.Fprintf(&sb, "%s\n\n", sec.Description)
+			}
+			for _, t := range secTasks {
+				sb.WriteString(taskBullet(t))
+				sb.WriteString("\n")
+				if t.Notes != "" {
+					sb.WriteString(notesBlock(t.Notes))
+				}
+			}
+		}
+	}
+
+	// Render orphan phases: tasks with a phaseID not in list.Phases.
+	var orphanIDs []string
+	for id := range byPhase {
+		if id != "" && !knownPhaseIDs[id] {
+			orphanIDs = append(orphanIDs, id)
+		}
+	}
+	sort.Strings(orphanIDs)
+	for _, id := range orphanIDs {
+		fmt.Fprintf(&sb, "## %s\n\n", id)
+		for _, t := range byPhase[id] {
+			sb.WriteString(taskBullet(t))
+			sb.WriteString("\n")
+			if t.Notes != "" {
+				sb.WriteString(notesBlock(t.Notes))
+			}
+		}
+	}
+
+	// Tasks with no phase
+	if noPhase := byPhase[""]; len(noPhase) > 0 {
+		sb.WriteString("## (none)\n\n")
+		for _, t := range noPhase {
+			sb.WriteString(taskBullet(t))
+			sb.WriteString("\n")
+			if t.Notes != "" {
+				sb.WriteString(notesBlock(t.Notes))
+			}
+		}
+	}
+
+	return sb.String()
+}
diff --git a/internal/task/format_test.go b/internal/task/format_test.go
new file mode 100644
index 0000000..a366f3b
--- /dev/null
+++ b/internal/task/format_test.go
@@ -0,0 +1,503 @@
+package task
+
+import (
+	"encoding/json"
+	"strings"
+	"testing"
+	"time"
+)
+
+var (
+	formatTestTime1 = time.Date(2026, 3, 10, 14, 22, 0, 0, time.UTC)
+	formatTestTime2 = time.Date(2026, 3, 10, 13, 0, 0, 0, time.UTC)
+)
+
+func TestFormatTaskMarkdown(t *testing.T) {
+	list := &TaskList{
+		Phases: []Phase{
+			{ID: "d4e5f6a7", Name: "Phase 1: Run Loop"},
+		},
+		Sections: []Section{
+			{ID: "b8c9d0e1", PhaseID: "d4e5f6a7", Name: "1.1 Output Formatting"},
+		},
+	}
+
+	t.Run("all fields present", func(t *testing.T) {
+		task := &Task{
+			ID:          "a3f7b2c1",
+			Subject:     "Implement stream-JSON output parsing",
+			Status:      StatusCompleted,
+			PhaseID:     "d4e5f6a7",
+			SectionID:   "b8c9d0e1",
+			Notes:       "Scans stdout line-by-line as newline-delimited JSON. Skips empty lines and parse failures gracefully.",
+			LastUpdated: formatTestTime1,
+		}
+		want := "# Implement stream-JSON output parsing\n\n**Status:** completed\n**Phase:** Phase 1: Run Loop\n**Section:** 1.1 Output Formatting\n**Updated:** 2026-03-10T14:22:00Z\n\nScans stdout line-by-line as newline-delimited JSON. Skips empty lines and parse failures gracefully.\n"
+		got := FormatTaskMarkdown(task, list)
+		if got != want {
+			t.Errorf("got:\n%q\nwant:\n%q", got, want)
+		}
+	})
+
+	t.Run("no phase or section", func(t *testing.T) {
+		task := &Task{
+			ID:          "c2a9e5b3",
+			Subject:     "Add usage examples to README",
+			Status:      StatusPending,
+			LastUpdated: formatTestTime2,
+		}
+		want := "# Add usage examples to README\n\n**Status:** pending\n**Updated:** 2026-03-10T13:00:00Z\n\n**Notes:** (none)\n"
+		got := FormatTaskMarkdown(task, list)
+		if got != want {
+			t.Errorf("got:\n%q\nwant:\n%q", got, want)
+		}
+	})
+
+	t.Run("phase and section IDs not in list use hex fallback", func(t *testing.T) {
+		task := &Task{
+			ID:          "a1b2c3d4",
+			Subject:     "Orphan task",
+			Status:      StatusPending,
+			PhaseID:     "deadbeef",
+			SectionID:   "cafebabe",
+			LastUpdated: formatTestTime1,
+		}
+		got := FormatTaskMarkdown(task, list)
+		if !strings.Contains(got, "**Phase:** deadbeef") {
+			t.Errorf("expected hex phase ID fallback, got:\n%s", got)
+		}
+		if !strings.Contains(got, "**Section:** cafebabe") {
+			t.Errorf("expected hex section ID fallback, got:\n%s", got)
+		}
+	})
+
+	t.Run("empty notes shows none", func(t *testing.T) {
+		task := &Task{
+			ID:          "a3f7b2c1",
+			Subject:     "Implement stream-JSON output parsing",
+			Status:      StatusCompleted,
+			PhaseID:     "d4e5f6a7",
+			SectionID:   "b8c9d0e1",
+			Notes:       "",
+			LastUpdated: formatTestTime1,
+		}
+		got := FormatTaskMarkdown(task, list)
+		if !strings.Contains(got, "**Notes:** (none)") {
+			t.Errorf("expected '**Notes:** (none)' for empty notes, got:\n%s", got)
+		}
+	})
+}
+
+func TestFormatTaskJSON(t *testing.T) {
+	task := &Task{
+		ID:          "a3f7b2c1",
+		Subject:     "Implement stream-JSON output parsing",
+		Status:      StatusCompleted,
+		PhaseID:     "d4e5f6a7",
+		SectionID:   "b8c9d0e1",
+		Notes:       "Scans stdout.",
+		LastUpdated: formatTestTime1,
+	}
+	got, err := FormatTaskJSON(task)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	// Must not be wrapped in a {"tasks": ...} envelope
+	if strings.Contains(got, `"tasks"`) {
+		t.Errorf("expected direct task JSON, not envelope: %s", got)
+	}
+
+	// Valid JSON that round-trips to the task
+	var decoded Task
+	if err := json.Unmarshal([]byte(got), &decoded); err != nil {
+		t.Fatalf("output is not valid JSON: %v\noutput: %s", err, got)
+	}
+	if decoded.ID != task.ID {
+		t.Errorf("ID: got %q, want %q", decoded.ID, task.ID)
+	}
+	if decoded.Subject != task.Subject {
+		t.Errorf("Subject: got %q, want %q", decoded.Subject, task.Subject)
+	}
+	if decoded.Status != task.Status {
+		t.Errorf("Status: got %q, want %q", decoded.Status, task.Status)
+	}
+}
+
+func TestFormatListJSON(t *testing.T) {
+	tasks := []Task{
+		{ID: "a3f7b2c1", Subject: "Task A", Status: StatusCompleted, LastUpdated: formatTestTime1},
+		{ID: "b8e4d1f0", Subject: "Task B", Status: StatusPending, LastUpdated: formatTestTime2},
+	}
+	got, err := FormatListJSON(tasks)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	// Must be wrapped in {"tasks": [...]}
+	var envelope struct {
+		Tasks []Task `json:"tasks"`
+	}
+	if err := json.Unmarshal([]byte(got), &envelope); err != nil {
+		t.Fatalf("output is not valid JSON: %v\noutput: %s", err, got)
+	}
+	if len(envelope.Tasks) != 2 {
+		t.Errorf("expected 2 tasks in envelope, got %d", len(envelope.Tasks))
+	}
+	if envelope.Tasks[0].ID != "a3f7b2c1" {
+		t.Errorf("first task ID: got %q, want %q", envelope.Tasks[0].ID, "a3f7b2c1")
+	}
+	if envelope.Tasks[1].ID != "b8e4d1f0" {
+		t.Errorf("second task ID: got %q, want %q", envelope.Tasks[1].ID, "b8e4d1f0")
+	}
+}
+
+func TestFormatListMarkdown(t *testing.T) {
+	list := &TaskList{
+		Name:        "My Project",
+		Description: "Project description.",
+		Phases: []Phase{
+			{ID: "d4e5f6a7", Name: "Phase 1: Run Loop"},
+		},
+		Sections: []Section{
+			{ID: "b8c9d0e1", PhaseID: "d4e5f6a7", Name: "1.1 Output Formatting"},
+			{ID: "f2a3b4c5", PhaseID: "d4e5f6a7", Name: "1.2 Signal Handling"},
+		},
+	}
+
+	tasks := []Task{
+		{
+			ID: "d6e7f8a9", Subject: "Add tool input truncation", Status: StatusPending,
+			PhaseID: "d4e5f6a7", SectionID: "b8c9d0e1",
+			Notes:       "Tool inputs currently show full content.",
+			LastUpdated: formatTestTime1,
+		},
+		{
+			ID: "c1d2e3f4", Subject: "Implement two-signal graceful shutdown", Status: StatusPending,
+			PhaseID: "d4e5f6a7", SectionID: "f2a3b4c5",
+			LastUpdated: formatTestTime2,
+		},
+	}
+
+	t.Run("grouped by phase and section", func(t *testing.T) {
+		got := FormatListMarkdown(tasks, list, false)
+
+		// No project H1 in list output
+		if strings.Contains(got, "# My Project") {
+			t.Errorf("list should not contain project H1, got:\n%s", got)
+		}
+		// Phase heading present
+		if !strings.Contains(got, "## Phase 1: Run Loop") {
+			t.Errorf("expected phase heading, got:\n%s", got)
+		}
+		// Section headings present
+		if !strings.Contains(got, "### 1.1 Output Formatting") {
+			t.Errorf("expected section 1.1 heading, got:\n%s", got)
+		}
+		if !strings.Contains(got, "### 1.2 Signal Handling") {
+			t.Errorf("expected section 1.2 heading, got:\n%s", got)
+		}
+		// Task bullets present
+		if !strings.Contains(got, "- `d6e7f8a9` [pending] Add tool input truncation") {
+			t.Errorf("expected task bullet for d6e7f8a9, got:\n%s", got)
+		}
+		if !strings.Contains(got, "- `c1d2e3f4` [pending] Implement two-signal graceful shutdown") {
+			t.Errorf("expected task bullet for c1d2e3f4, got:\n%s", got)
+		}
+		// Notes block with 2-space indented fence
+		if !strings.Contains(got, "  ```notes") {
+			t.Errorf("expected indented notes opening fence, got:\n%s", got)
+		}
+		if !strings.Contains(got, "  Tool inputs currently show full content.") {
+			t.Errorf("expected indented notes content, got:\n%s", got)
+		}
+	})
+
+	t.Run("sections with zero matching tasks omitted", func(t *testing.T) {
+		// Only tasks in section b8c9d0e1 (1.1 Output Formatting)
+		got := FormatListMarkdown(tasks[:1], list, false)
+		if !strings.Contains(got, "### 1.1 Output Formatting") {
+			t.Errorf("expected 1.1 section heading, got:\n%s", got)
+		}
+		// 1.2 should be omitted since no tasks match
+		if strings.Contains(got, "### 1.2 Signal Handling") {
+			t.Errorf("1.2 section should be omitted (no tasks), got:\n%s", got)
+		}
+	})
+
+	t.Run("phase name hex fallback", func(t *testing.T) {
+		listNoName := &TaskList{
+			Phases:   []Phase{{ID: "a1b2c3d4"}}, // no name
+			Sections: []Section{},
+		}
+		noNameTasks := []Task{
+			{ID: "e5f6a7b8", Subject: "Task in unnamed phase", Status: StatusPending, PhaseID: "a1b2c3d4", LastUpdated: formatTestTime1},
+		}
+		got := FormatListMarkdown(noNameTasks, listNoName, false)
+		if !strings.Contains(got, "## a1b2c3d4") {
+			t.Errorf("expected hex phase ID heading as fallback, got:\n%s", got)
+		}
+	})
+
+	t.Run("section name hex fallback", func(t *testing.T) {
+		listNoName := &TaskList{
+			Phases:   []Phase{{ID: "d4e5f6a7", Name: "Phase 1"}},
+			Sections: []Section{{ID: "a1b2c3d4", PhaseID: "d4e5f6a7"}}, // no name
+		}
+		noNameTasks := []Task{
+			{ID: "e5f6a7b8", Subject: "Task in unnamed section", Status: StatusPending, PhaseID: "d4e5f6a7", SectionID: "a1b2c3d4", LastUpdated: formatTestTime1},
+		}
+		got := FormatListMarkdown(noNameTasks, listNoName, false)
+		if !strings.Contains(got, "### a1b2c3d4") {
+			t.Errorf("expected hex section ID heading as fallback, got:\n%s", got)
+		}
+	})
+
+	t.Run("tasks with no phase collected under (none)", func(t *testing.T) {
+		noPhaseTask := Task{ID: "aaaabbbb", Subject: "Orphan task", Status: StatusPending, LastUpdated: formatTestTime1}
+		got := FormatListMarkdown([]Task{noPhaseTask}, list, false)
+		if !strings.Contains(got, "## (none)") {
+			t.Errorf("expected '## (none)' heading for tasks without phase, got:\n%s", got)
+		}
+		if !strings.Contains(got, "- `aaaabbbb` [pending] Orphan task") {
+			t.Errorf("expected task bullet under (none), got:\n%s", got)
+		}
+	})
+
+	t.Run("tasks without section appear directly under phase heading", func(t *testing.T) {
+		noSectionTask := Task{
+			ID: "e5f6a7b8", Subject: "Phase-only task", Status: StatusPending,
+			PhaseID:     "d4e5f6a7",
+			LastUpdated: formatTestTime1,
+		}
+		got := FormatListMarkdown([]Task{noSectionTask}, list, false)
+		if !strings.Contains(got, "## Phase 1: Run Loop") {
+			t.Errorf("expected phase heading, got:\n%s", got)
+		}
+		// No section heading (no H3)
+		if strings.Contains(got, "### ") {
+			t.Errorf("no section heading expected for task with no section, got:\n%s", got)
+		}
+		if !strings.Contains(got, "- `e5f6a7b8` [pending] Phase-only task") {
+			t.Errorf("expected task bullet, got:\n%s", got)
+		}
+	})
+
+	t.Run("tasks without notes render as bare bullets", func(t *testing.T) {
+		noNotesTasks := []Task{
+			{
+				ID: "c1d2e3f4", Subject: "No notes task", Status: StatusPending,
+				PhaseID: "d4e5f6a7", SectionID: "f2a3b4c5",
+				LastUpdated: formatTestTime2,
+			},
+		}
+		got := FormatListMarkdown(noNotesTasks, list, false)
+		if !strings.Contains(got, "- `c1d2e3f4` [pending] No notes task") {
+			t.Errorf("expected task bullet, got:\n%s", got)
+		}
+		if strings.Contains(got, "```notes") {
+			t.Errorf("expected no notes block for task without notes, got:\n%s", got)
+		}
+	})
+
+	t.Run("ordering by phase position then section position", func(t *testing.T) {
+		orderedList := &TaskList{
+			Phases: []Phase{
+				{ID: "phase001", Name: "Phase A"},
+				{ID: "phase002", Name: "Phase B"},
+			},
+			Sections: []Section{
+				{ID: "sect0001", PhaseID: "phase001", Name: "Section A1"},
+				{ID: "sect0002", PhaseID: "phase001", Name: "Section A2"},
+			},
+		}
+		orderedTasks := []Task{
+			{ID: "task0003", Subject: "Task in B", Status: StatusPending, PhaseID: "phase002", LastUpdated: formatTestTime1},
+			{ID: "task0002", Subject: "Task in A2", Status: StatusPending, PhaseID: "phase001", SectionID: "sect0002", LastUpdated: formatTestTime1},
+			{ID: "task0001", Subject: "Task in A1", Status: StatusPending, PhaseID: "phase001", SectionID: "sect0001", LastUpdated: formatTestTime1},
+		}
+		got := FormatListMarkdown(orderedTasks, orderedList, false)
+		posPhaseA := strings.Index(got, "## Phase A")
+		posPhaseB := strings.Index(got, "## Phase B")
+		posSectA1 := strings.Index(got, "### Section A1")
+		posSectA2 := strings.Index(got, "### Section A2")
+		if posPhaseA < 0 || posPhaseB < 0 {
+			t.Fatalf("expected Phase A and Phase B headings, got:\n%s", got)
+		}
+		if posPhaseA >= posPhaseB {
+			t.Errorf("Phase A should appear before Phase B")
+		}
+		if posSectA1 < 0 || posSectA2 < 0 {
+			t.Fatalf("expected Section A1 and Section A2 headings, got:\n%s", got)
+		}
+		if posSectA1 >= posSectA2 {
+			t.Errorf("Section A1 should appear before Section A2")
+		}
+	})
+}
+
+func TestFormatListMarkdownFlat(t *testing.T) {
+	list := &TaskList{
+		Phases:   []Phase{{ID: "d4e5f6a7", Name: "Phase 1: Run Loop"}},
+		Sections: []Section{{ID: "b8c9d0e1", PhaseID: "d4e5f6a7", Name: "1.1 Output Formatting"}},
+	}
+	tasks := []Task{
+		{
+			ID: "d6e7f8a9", Subject: "Add tool input truncation", Status: StatusPending,
+			PhaseID: "d4e5f6a7", SectionID: "b8c9d0e1",
+			Notes:       "Some notes.",
+			LastUpdated: formatTestTime1,
+		},
+		{
+			ID: "c1d2e3f4", Subject: "Implement two-signal graceful shutdown", Status: StatusPending,
+			PhaseID: "d4e5f6a7", SectionID: "b8c9d0e1",
+			LastUpdated: formatTestTime2,
+		},
+	}
+
+	got := FormatListMarkdown(tasks, list, true)
+
+	// No phase or section headings
+	if strings.Contains(got, "## ") || strings.Contains(got, "### ") {
+		t.Errorf("flat mode should not contain headings, got:\n%s", got)
+	}
+	// No notes blocks
+	if strings.Contains(got, "```notes") {
+		t.Errorf("flat mode should not contain notes, got:\n%s", got)
+	}
+	// Task bullets present
+	if !strings.Contains(got, "- `d6e7f8a9` [pending] Add tool input truncation") {
+		t.Errorf("expected task bullet for d6e7f8a9, got:\n%s", got)
+	}
+	if !strings.Contains(got, "- `c1d2e3f4` [pending] Implement two-signal graceful shutdown") {
+		t.Errorf("expected task bullet for c1d2e3f4, got:\n%s", got)
+	}
+}
+
+func TestFormatExportMarkdown(t *testing.T) {
+	list := &TaskList{
+		Name:        "Lorah Development Plan",
+		Description: "Track progress on the Lorah infinite-loop harness implementation.",
+		Phases: []Phase{
+			{ID: "d4e5f6a7", Name: "Phase 1: Run Loop", Description: "Implement the infinite loop."},
+		},
+		Sections: []Section{
+			{ID: "b8c9d0e1", PhaseID: "d4e5f6a7", Name: "1.1 Output Formatting"},
+		},
+	}
+	tasks := []Task{
+		{
+			ID: "a3f7b2c1", Subject: "Implement stream-JSON output parsing", Status: StatusCompleted,
+			PhaseID: "d4e5f6a7", SectionID: "b8c9d0e1",
+			Notes:       "Scans stdout line-by-line.",
+			LastUpdated: formatTestTime1,
+		},
+	}
+
+	t.Run("project name H1 and description present", func(t *testing.T) {
+		got := FormatExportMarkdown(tasks, list)
+		if !strings.Contains(got, "# Lorah Development Plan") {
+			t.Errorf("expected project H1, got:\n%s", got)
+		}
+		if !strings.Contains(got, "Track progress on the Lorah infinite-loop harness implementation.") {
+			t.Errorf("expected project description, got:\n%s", got)
+		}
+	})
+
+	t.Run("phase heading and description present", func(t *testing.T) {
+		got := FormatExportMarkdown(tasks, list)
+		if !strings.Contains(got, "## Phase 1: Run Loop") {
+			t.Errorf("expected phase heading, got:\n%s", got)
+		}
+		if !strings.Contains(got, "Implement the infinite loop.") {
+			t.Errorf("expected phase description, got:\n%s", got)
+		}
+	})
+
+	t.Run("section heading and task bullet with notes", func(t *testing.T) {
+		got := FormatExportMarkdown(tasks, list)
+		if !strings.Contains(got, "### 1.1 Output Formatting") {
+			t.Errorf("expected section heading, got:\n%s", got)
+		}
+		if !strings.Contains(got, "- `a3f7b2c1` [completed] Implement stream-JSON output parsing") {
+			t.Errorf("expected task bullet, got:\n%s", got)
+		}
+		if !strings.Contains(got, "  ```notes") {
+			t.Errorf("expected indented notes fence, got:\n%s", got)
+		}
+		if !strings.Contains(got, "  Scans stdout line-by-line.") {
+			t.Errorf("expected indented notes content, got:\n%s", got)
+		}
+	})
+
+	t.Run("no name skips H1 and description", func(t *testing.T) {
+		listNoName := &TaskList{
+			Description: "Some description.",
+			Phases:      list.Phases,
+			Sections:    list.Sections,
+		}
+		got := FormatExportMarkdown(tasks, listNoName)
+		if strings.HasPrefix(got, "# ") {
+			t.Errorf("expected no H1 when name is empty, got:\n%s", got)
+		}
+		// Description skipped when name is absent
+		if strings.Contains(got, "Some description.") {
+			t.Errorf("description should be skipped when name is absent, got:\n%s", got)
+		}
+	})
+
+	t.Run("tasks with no phase collected under (none)", func(t *testing.T) {
+		noPhaseTask := Task{
+			ID: "aaaabbbb", Subject: "Orphan task", Status: StatusPending,
+			LastUpdated: formatTestTime1,
+		}
+		got := FormatExportMarkdown([]Task{noPhaseTask}, list)
+		if !strings.Contains(got, "## (none)") {
+			t.Errorf("expected '## (none)' heading for tasks without phase, got:\n%s", got)
+		}
+	})
+
+	t.Run("section description renders below section heading", func(t *testing.T) {
+		listWithSectionDesc := &TaskList{
+			Name: "My Project",
+			Phases: []Phase{
+				{ID: "d4e5f6a7", Name: "Phase 1: Run Loop"},
+			},
+			Sections: []Section{
+				{ID: "b8c9d0e1", PhaseID: "d4e5f6a7", Name: "1.1 Output Formatting", Description: "Handles stream-JSON parsing."},
+			},
+		}
+		got := FormatExportMarkdown(tasks, listWithSectionDesc)
+		if !strings.Contains(got, "### 1.1 Output Formatting") {
+			t.Errorf("expected section heading, got:\n%s", got)
+		}
+		if !strings.Contains(got, "Handles stream-JSON parsing.") {
+			t.Errorf("expected section description in export output, got:\n%s", got)
+		}
+	})
+
+	t.Run("no description paragraph when description is empty", func(t *testing.T) {
+		listNoDesc := &TaskList{
+			Name: "My Project",
+			Phases: []Phase{
+				{ID: "d4e5f6a7", Name: "Phase 1: Run Loop"}, // no description
+			},
+			Sections: []Section{
+				{ID: "b8c9d0e1", PhaseID: "d4e5f6a7", Name: "1.1 Output Formatting"}, // no description
+			},
+		}
+		got := FormatExportMarkdown(tasks, listNoDesc)
+		// Phase heading must be present
+		if !strings.Contains(got, "## Phase 1: Run Loop") {
+			t.Errorf("expected phase heading, got:\n%s", got)
+		}
+		// No "(none)" placeholder for missing descriptions
+		if strings.Contains(got, "(none)") {
+			t.Errorf("expected no placeholder text for empty descriptions, got:\n%s", got)
+		}
+		// No consecutive blank lines beyond heading separators (no extra blank line from missing description)
+		if strings.Contains(got, "\n\n\n") {
+			t.Errorf("unexpected triple newline (extra blank line) from empty description, got:\n%q", got)
+		}
+	})
+}
diff --git a/internal/task/json_storage.go b/internal/task/json_storage.go
new file mode 100644
index 0000000..55a6725
--- /dev/null
+++ b/internal/task/json_storage.go
@@ -0,0 +1,148 @@
+package task
+
+import (
+	"encoding/json"
+	"fmt"
+	"os"
+	"sync"
+	"time"
+)
+
+// JSONStorage implements Storage using a JSON file on disk.
+type JSONStorage struct {
+	mu   sync.RWMutex
+	path string
+}
+
+// NewJSONStorage returns a JSONStorage backed by the given file path.
+func NewJSONStorage(path string) *JSONStorage {
+	return &JSONStorage{path: path}
+}
+
+func (s *JSONStorage) Load() (*TaskList, error) {
+	s.mu.RLock()
+	defer s.mu.RUnlock()
+
+	data, err := os.ReadFile(s.path)
+	if err != nil {
+		if os.IsNotExist(err) {
+			return &TaskList{Version: "1.0"}, nil
+		}
+		return nil, err
+	}
+
+	var list TaskList
+	if err := json.Unmarshal(data, &list); err != nil {
+		return nil, err
+	}
+	return &list, nil
+}
+
+func (s *JSONStorage) Save(list *TaskList) error {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+
+	list.LastUpdated = time.Now().UTC()
+
+	data, err := json.MarshalIndent(list, "", "  ")
+	if err != nil {
+		return err
+	}
+	return os.WriteFile(s.path, data, 0644)
+}
+
+func (s *JSONStorage) Get(id string) (*Task, error) {
+	list, err := s.Load()
+	if err != nil {
+		return nil, err
+	}
+	for i := range list.Tasks {
+		if list.Tasks[i].ID == id {
+			t := list.Tasks[i]
+			return &t, nil
+		}
+	}
+	return nil, fmt.Errorf("task %q not found", id)
+}
+
+func (s *JSONStorage) List(filter Filter) ([]Task, error) {
+	list, err := s.Load()
+	if err != nil {
+		return nil, err
+	}
+
+	var results []Task
+	for _, t := range list.Tasks {
+		if len(filter.Status) > 0 {
+			matched := false
+			for _, s := range filter.Status {
+				if t.Status == s {
+					matched = true
+					break
+				}
+			}
+			if !matched {
+				continue
+			}
+		}
+		if filter.PhaseID != "" && t.PhaseID != filter.PhaseID {
+			continue
+		}
+		if filter.SectionID != "" && t.SectionID != filter.SectionID {
+			continue
+		}
+		results = append(results, t)
+		if filter.Limit > 0 && len(results) >= filter.Limit {
+			break
+		}
+	}
+
+	if results == nil {
+		results = []Task{}
+	}
+	return results, nil
+}
+
+func (s *JSONStorage) Create(task *Task) error {
+	list, err := s.Load()
+	if err != nil {
+		return err
+	}
+	for _, t := range list.Tasks {
+		if t.ID == task.ID {
+			return fmt.Errorf("task with ID %q already exists", task.ID)
+		}
+	}
+	task.LastUpdated = time.Now().UTC()
+	list.Tasks = append(list.Tasks, *task)
+	return s.Save(list)
+}
+
+func (s *JSONStorage) Update(task *Task) error {
+	list, err := s.Load()
+	if err != nil {
+		return err
+	}
+	for i := range list.Tasks {
+		if list.Tasks[i].ID == task.ID {
+			task.LastUpdated = time.Now().UTC()
+			list.Tasks[i] = *task
+			return s.Save(list)
+		}
+	}
+	return fmt.Errorf("task %q not found", task.ID)
+}
+
+func (s *JSONStorage) Delete(id string) error {
+	list, err := s.Load()
+	if err != nil {
+		return err
+	}
+	for i, t := range list.Tasks {
+		if t.ID == id {
+			list.Tasks = append(list.Tasks[:i], list.Tasks[i+1:]...)
+			return s.Save(list)
+		}
+	}
+	return fmt.Errorf("task %q not found", id)
+}
diff --git a/internal/task/json_storage_test.go b/internal/task/json_storage_test.go
new file mode 100644
index 0000000..0a073b8
--- /dev/null
+++ b/internal/task/json_storage_test.go
@@ -0,0 +1,429 @@
+package task
+
+import (
+	"fmt"
+	"os"
+	"path/filepath"
+	"testing"
+	"time"
+)
+
+func newJSONStorage(t *testing.T) *JSONStorage {
+	t.Helper()
+	dir := t.TempDir()
+	return &JSONStorage{path: filepath.Join(dir, "tasks.json")}
+}
+
+func TestLoadNonExistent(t *testing.T) {
+	s := newJSONStorage(t)
+	list, err := s.Load()
+	if err != nil {
+		t.Fatalf("expected no error, got %v", err)
+	}
+	if list.Version != "1.0" {
+		t.Errorf("expected Version %q, got %q", "1.0", list.Version)
+	}
+	if len(list.Tasks) != 0 {
+		t.Errorf("expected empty tasks, got %d", len(list.Tasks))
+	}
+}
+
+func TestLoadExistingFile(t *testing.T) {
+	s := newJSONStorage(t)
+	original := &TaskList{
+		Name:        "Test Project",
+		Description: "Project description",
+		Version:     "1.0",
+		Phases:      []Phase{{ID: "phid0001", Name: "Phase 1", Description: "Phase desc"}},
+		Sections:    []Section{{ID: "sect0001", PhaseID: "phid0001", Name: "Section 1"}},
+		Tasks: []Task{
+			{ID: "a1b2c3d4", Subject: "first task", Status: StatusPending, LastUpdated: time.Now().UTC().Truncate(time.Second)},
+		},
+	}
+	if err := s.Save(original); err != nil {
+		t.Fatalf("Save: %v", err)
+	}
+
+	list, err := s.Load()
+	if err != nil {
+		t.Fatalf("Load: %v", err)
+	}
+	if list.Name != "Test Project" {
+		t.Errorf("expected Name %q, got %q", "Test Project", list.Name)
+	}
+	if list.Description != "Project description" {
+		t.Errorf("expected Description %q, got %q", "Project description", list.Description)
+	}
+	if list.Version != "1.0" {
+		t.Errorf("expected Version %q, got %q", "1.0", list.Version)
+	}
+	if list.LastUpdated.IsZero() {
+		t.Error("expected LastUpdated to be set, got zero")
+	}
+	if len(list.Phases) != 1 || list.Phases[0].ID != "phid0001" || list.Phases[0].Name != "Phase 1" || list.Phases[0].Description != "Phase desc" {
+		t.Errorf("unexpected Phases: %v", list.Phases)
+	}
+	if len(list.Sections) != 1 || list.Sections[0].ID != "sect0001" || list.Sections[0].PhaseID != "phid0001" || list.Sections[0].Name != "Section 1" {
+		t.Errorf("unexpected Sections: %v", list.Sections)
+	}
+	if len(list.Tasks) != 1 {
+		t.Fatalf("expected 1 task, got %d", len(list.Tasks))
+	}
+	if list.Tasks[0].ID != "a1b2c3d4" {
+		t.Errorf("expected task ID %q, got %q", "a1b2c3d4", list.Tasks[0].ID)
+	}
+}
+
+func TestSaveUpdatesLastUpdatedAndRoundTrips(t *testing.T) {
+	s := newJSONStorage(t)
+	before := time.Now().UTC().Add(-time.Second)
+	list := &TaskList{Version: "1.0", Tasks: []Task{}}
+	if err := s.Save(list); err != nil {
+		t.Fatalf("Save: %v", err)
+	}
+	if list.LastUpdated.Before(before) {
+		t.Errorf("LastUpdated not updated: got %v", list.LastUpdated)
+	}
+
+	// Verify the file contains indented JSON (check for at least one newline + spaces)
+	data, err := os.ReadFile(s.path)
+	if err != nil {
+		t.Fatalf("ReadFile: %v", err)
+	}
+	content := string(data)
+	if len(content) == 0 {
+		t.Fatal("expected non-empty file")
+	}
+	// Indented JSON has newlines
+	hasNewline := false
+	for _, c := range content {
+		if c == '\n' {
+			hasNewline = true
+			break
+		}
+	}
+	if !hasNewline {
+		t.Error("expected indented JSON with newlines")
+	}
+
+	// Round-trip
+	loaded, err := s.Load()
+	if err != nil {
+		t.Fatalf("Load after Save: %v", err)
+	}
+	if !loaded.LastUpdated.Equal(list.LastUpdated) {
+		t.Errorf("LastUpdated round-trip mismatch: saved %v, loaded %v", list.LastUpdated, loaded.LastUpdated)
+	}
+}
+
+func TestSaveFilePermissions(t *testing.T) {
+	s := newJSONStorage(t)
+	list := &TaskList{Version: "1.0", Tasks: []Task{}}
+	if err := s.Save(list); err != nil {
+		t.Fatalf("Save: %v", err)
+	}
+	info, err := os.Stat(s.path)
+	if err != nil {
+		t.Fatalf("Stat: %v", err)
+	}
+	if got := info.Mode().Perm(); got != 0644 {
+		t.Errorf("expected file permissions 0644, got %04o", got)
+	}
+}
+
+func TestCreate(t *testing.T) {
+	s := newJSONStorage(t)
+	task := &Task{ID: "aaaabbbb", Subject: "new task", Status: StatusPending}
+	before := time.Now().UTC().Add(-time.Second)
+	if err := s.Create(task); err != nil {
+		t.Fatalf("Create: %v", err)
+	}
+	if task.LastUpdated.Before(before) {
+		t.Errorf("Create did not set LastUpdated: got %v", task.LastUpdated)
+	}
+
+	// Verify persisted
+	list, err := s.Load()
+	if err != nil {
+		t.Fatalf("Load after Create: %v", err)
+	}
+	if len(list.Tasks) != 1 {
+		t.Fatalf("expected 1 task, got %d", len(list.Tasks))
+	}
+	if list.Tasks[0].ID != "aaaabbbb" {
+		t.Errorf("expected task ID %q, got %q", "aaaabbbb", list.Tasks[0].ID)
+	}
+}
+
+func TestCreateDuplicateID(t *testing.T) {
+	s := newJSONStorage(t)
+	task := &Task{ID: "aaaabbbb", Subject: "task one", Status: StatusPending}
+	if err := s.Create(task); err != nil {
+		t.Fatalf("first Create: %v", err)
+	}
+	dup := &Task{ID: "aaaabbbb", Subject: "task two", Status: StatusPending}
+	if err := s.Create(dup); err == nil {
+		t.Fatal("expected error for duplicate ID, got nil")
+	}
+}
+
+func TestGet(t *testing.T) {
+	s := newJSONStorage(t)
+	task := &Task{ID: "ccccdddd", Subject: "findable", Status: StatusInProgress}
+	if err := s.Create(task); err != nil {
+		t.Fatalf("Create: %v", err)
+	}
+
+	got, err := s.Get("ccccdddd")
+	if err != nil {
+		t.Fatalf("Get: %v", err)
+	}
+	if got.Subject != "findable" {
+		t.Errorf("expected Subject %q, got %q", "findable", got.Subject)
+	}
+}
+
+func TestGetNotFound(t *testing.T) {
+	s := newJSONStorage(t)
+	_, err := s.Get("notexist")
+	if err == nil {
+		t.Fatal("expected error for missing task, got nil")
+	}
+}
+
+func TestListNoFilter(t *testing.T) {
+	s := newJSONStorage(t)
+	tasks := []Task{
+		{ID: "id000001", Subject: "pending task", Status: StatusPending},
+		{ID: "id000002", Subject: "in-progress task", Status: StatusInProgress},
+		{ID: "id000003", Subject: "completed task", Status: StatusCompleted},
+	}
+	for i := range tasks {
+		if err := s.Create(&tasks[i]); err != nil {
+			t.Fatalf("Create task %d: %v", i, err)
+		}
+	}
+
+	results, err := s.List(Filter{})
+	if err != nil {
+		t.Fatalf("List: %v", err)
+	}
+	if len(results) != 3 {
+		t.Errorf("expected 3 results, got %d", len(results))
+	}
+}
+
+func TestListFilterByStatus(t *testing.T) {
+	s := newJSONStorage(t)
+	tasks := []Task{
+		{ID: "id000001", Subject: "pending task", Status: StatusPending},
+		{ID: "id000002", Subject: "in-progress task", Status: StatusInProgress},
+		{ID: "id000003", Subject: "completed task", Status: StatusCompleted},
+	}
+	for i := range tasks {
+		if err := s.Create(&tasks[i]); err != nil {
+			t.Fatalf("Create task %d: %v", i, err)
+		}
+	}
+
+	results, err := s.List(Filter{Status: []TaskStatus{StatusPending}})
+	if err != nil {
+		t.Fatalf("List: %v", err)
+	}
+	if len(results) != 1 {
+		t.Fatalf("expected 1 result, got %d", len(results))
+	}
+	if results[0].ID != "id000001" {
+		t.Errorf("expected ID %q, got %q", "id000001", results[0].ID)
+	}
+}
+
+func TestListFilterByMultipleStatuses(t *testing.T) {
+	s := newJSONStorage(t)
+	tasks := []Task{
+		{ID: "id000001", Subject: "pending task", Status: StatusPending},
+		{ID: "id000002", Subject: "in-progress task", Status: StatusInProgress},
+		{ID: "id000003", Subject: "completed task", Status: StatusCompleted},
+	}
+	for i := range tasks {
+		if err := s.Create(&tasks[i]); err != nil {
+			t.Fatalf("Create task %d: %v", i, err)
+		}
+	}
+
+	results, err := s.List(Filter{Status: []TaskStatus{StatusPending, StatusInProgress}})
+	if err != nil {
+		t.Fatalf("List: %v", err)
+	}
+	if len(results) != 2 {
+		t.Fatalf("expected 2 results, got %d", len(results))
+	}
+	ids := map[string]bool{results[0].ID: true, results[1].ID: true}
+	if !ids["id000001"] || !ids["id000002"] {
+		t.Errorf("expected ids id000001 and id000002, got %v", ids)
+	}
+}
+
+func TestListFilterCombined(t *testing.T) {
+	s := newJSONStorage(t)
+	tasks := []Task{
+		{ID: "id000001", Subject: "pending in phase", Status: StatusPending, PhaseID: "phase001"},
+		{ID: "id000002", Subject: "completed in phase", Status: StatusCompleted, PhaseID: "phase001"},
+		{ID: "id000003", Subject: "pending no phase", Status: StatusPending},
+	}
+	for i := range tasks {
+		if err := s.Create(&tasks[i]); err != nil {
+			t.Fatalf("Create task %d: %v", i, err)
+		}
+	}
+
+	results, err := s.List(Filter{Status: []TaskStatus{StatusPending}, PhaseID: "phase001"})
+	if err != nil {
+		t.Fatalf("List: %v", err)
+	}
+	if len(results) != 1 {
+		t.Fatalf("expected 1 result, got %d", len(results))
+	}
+	if results[0].ID != "id000001" {
+		t.Errorf("expected ID %q, got %q", "id000001", results[0].ID)
+	}
+}
+
+func TestListFilterByPhaseID(t *testing.T) {
+	s := newJSONStorage(t)
+	tasks := []Task{
+		{ID: "id000001", Subject: "in phase", Status: StatusPending, PhaseID: "phase001"},
+		{ID: "id000002", Subject: "no phase", Status: StatusPending},
+	}
+	for i := range tasks {
+		if err := s.Create(&tasks[i]); err != nil {
+			t.Fatalf("Create: %v", err)
+		}
+	}
+
+	results, err := s.List(Filter{PhaseID: "phase001"})
+	if err != nil {
+		t.Fatalf("List: %v", err)
+	}
+	if len(results) != 1 || results[0].ID != "id000001" {
+		t.Errorf("unexpected results: %v", results)
+	}
+}
+
+func TestListFilterBySectionID(t *testing.T) {
+	s := newJSONStorage(t)
+	tasks := []Task{
+		{ID: "id000001", Subject: "in section", Status: StatusPending, SectionID: "sect0001"},
+		{ID: "id000002", Subject: "no section", Status: StatusPending},
+	}
+	for i := range tasks {
+		if err := s.Create(&tasks[i]); err != nil {
+			t.Fatalf("Create: %v", err)
+		}
+	}
+
+	results, err := s.List(Filter{SectionID: "sect0001"})
+	if err != nil {
+		t.Fatalf("List: %v", err)
+	}
+	if len(results) != 1 || results[0].ID != "id000001" {
+		t.Errorf("unexpected results: %v", results)
+	}
+}
+
+func TestListFilterLimit(t *testing.T) {
+	s := newJSONStorage(t)
+	for i := 0; i < 5; i++ {
+		task := &Task{ID: fmt.Sprintf("id00000%d", i), Subject: fmt.Sprintf("task %d", i), Status: StatusPending}
+		if err := s.Create(task); err != nil {
+			t.Fatalf("Create task %d: %v", i, err)
+		}
+	}
+
+	results, err := s.List(Filter{Limit: 3})
+	if err != nil {
+		t.Fatalf("List: %v", err)
+	}
+	if len(results) != 3 {
+		t.Errorf("expected 3 results (limit), got %d", len(results))
+	}
+}
+
+func TestListNoLimit(t *testing.T) {
+	s := newJSONStorage(t)
+	for i := 0; i < 5; i++ {
+		task := &Task{ID: fmt.Sprintf("id00000%d", i), Subject: fmt.Sprintf("task %d", i), Status: StatusPending}
+		if err := s.Create(task); err != nil {
+			t.Fatalf("Create task %d: %v", i, err)
+		}
+	}
+
+	results, err := s.List(Filter{Limit: 0})
+	if err != nil {
+		t.Fatalf("List: %v", err)
+	}
+	if len(results) != 5 {
+		t.Errorf("expected 5 results (no limit), got %d", len(results))
+	}
+}
+
+func TestUpdate(t *testing.T) {
+	s := newJSONStorage(t)
+	task := &Task{ID: "updateid", Subject: "original", Status: StatusPending}
+	if err := s.Create(task); err != nil {
+		t.Fatalf("Create: %v", err)
+	}
+
+	before := time.Now().UTC().Add(-time.Second)
+	task.Subject = "updated"
+	task.Status = StatusCompleted
+	if err := s.Update(task); err != nil {
+		t.Fatalf("Update: %v", err)
+	}
+	if task.LastUpdated.Before(before) {
+		t.Errorf("Update did not set LastUpdated: got %v", task.LastUpdated)
+	}
+
+	got, err := s.Get("updateid")
+	if err != nil {
+		t.Fatalf("Get after Update: %v", err)
+	}
+	if got.Subject != "updated" {
+		t.Errorf("expected Subject %q, got %q", "updated", got.Subject)
+	}
+	if got.Status != StatusCompleted {
+		t.Errorf("expected Status %q, got %q", StatusCompleted, got.Status)
+	}
+}
+
+func TestUpdateNotFound(t *testing.T) {
+	s := newJSONStorage(t)
+	task := &Task{ID: "missing0", Subject: "ghost", Status: StatusPending}
+	if err := s.Update(task); err == nil {
+		t.Fatal("expected error for missing task, got nil")
+	}
+}
+
+func TestDelete(t *testing.T) {
+	s := newJSONStorage(t)
+	task := &Task{ID: "deleteid", Subject: "to delete", Status: StatusPending}
+	if err := s.Create(task); err != nil {
+		t.Fatalf("Create: %v", err)
+	}
+
+	if err := s.Delete("deleteid"); err != nil {
+		t.Fatalf("Delete: %v", err)
+	}
+
+	_, err := s.Get("deleteid")
+	if err == nil {
+		t.Fatal("expected error after Delete, got nil")
+	}
+}
+
+func TestDeleteNotFound(t *testing.T) {
+	s := newJSONStorage(t)
+	if err := s.Delete("notfound"); err == nil {
+		t.Fatal("expected error for missing task, got nil")
+	}
+}
diff --git a/internal/task/storage.go b/internal/task/storage.go
new file mode 100644
index 0000000..2fc255b
--- /dev/null
+++ b/internal/task/storage.go
@@ -0,0 +1,12 @@
+package task
+
+// Storage is the interface for task persistence.
+type Storage interface {
+	Load() (*TaskList, error)
+	Save(list *TaskList) error
+	Get(id string) (*Task, error)
+	List(filter Filter) ([]Task, error)
+	Create(task *Task) error
+	Update(task *Task) error
+	Delete(id string) error
+}
diff --git a/internal/task/task.go b/internal/task/task.go
new file mode 100644
index 0000000..1256967
--- /dev/null
+++ b/internal/task/task.go
@@ -0,0 +1,70 @@
+package task
+
+import (
+	"crypto/rand"
+	"encoding/hex"
+	"time"
+)
+
+// TaskStatus represents the status of a task.
+type TaskStatus string
+
+const (
+	StatusPending    TaskStatus = "pending"
+	StatusInProgress TaskStatus = "in_progress"
+	StatusCompleted  TaskStatus = "completed"
+)
+
+// Phase groups related sections and tasks.
+type Phase struct {
+	ID          string `json:"id"`
+	Name        string `json:"name,omitempty"`
+	Description string `json:"description,omitempty"`
+}
+
+// Section groups related tasks within a phase.
+type Section struct {
+	ID          string `json:"id"`
+	PhaseID     string `json:"phaseId"`
+	Name        string `json:"name,omitempty"`
+	Description string `json:"description,omitempty"`
+}
+
+// Task is a unit of work.
+type Task struct {
+	ID          string     `json:"id"`
+	Subject     string     `json:"subject"`
+	Status      TaskStatus `json:"status"`
+	PhaseID     string     `json:"phaseId,omitempty"`
+	SectionID   string     `json:"sectionId,omitempty"`
+	Notes       string     `json:"notes,omitempty"`
+	LastUpdated time.Time  `json:"lastUpdated"`
+}
+
+// TaskList is the root structure stored in tasks.json.
+type TaskList struct {
+	Name        string    `json:"name,omitempty"`
+	Description string    `json:"description,omitempty"`
+	Phases      []Phase   `json:"phases,omitempty"`
+	Sections    []Section `json:"sections,omitempty"`
+	Tasks       []Task    `json:"tasks"`
+	Version     string    `json:"version"`
+	LastUpdated time.Time `json:"lastUpdated"`
+}
+
+// Filter limits results from a storage List query.
+type Filter struct {
+	Status    []TaskStatus
+	PhaseID   string
+	SectionID string
+	Limit     int
+}
+
+// generateID returns a unique 8-character lowercase hex string.
+func generateID() string {
+	b := make([]byte, 4)
+	if _, err := rand.Read(b); err != nil {
+		panic("generateID: " + err.Error())
+	}
+	return hex.EncodeToString(b)
+}
diff --git a/internal/task/task_test.go b/internal/task/task_test.go
new file mode 100644
index 0000000..0afb887
--- /dev/null
+++ b/internal/task/task_test.go
@@ -0,0 +1,215 @@
+package task
+
+import (
+	"encoding/json"
+	"regexp"
+	"testing"
+	"time"
+)
+
+// TestTaskStatusConstants verifies the string values of TaskStatus constants.
+func TestTaskStatusConstants(t *testing.T) {
+	tests := []struct {
+		status TaskStatus
+		want   string
+	}{
+		{StatusPending, "pending"},
+		{StatusInProgress, "in_progress"},
+		{StatusCompleted, "completed"},
+	}
+	for _, tt := range tests {
+		if string(tt.status) != tt.want {
+			t.Errorf("status %q = %q, want %q", tt.status, string(tt.status), tt.want)
+		}
+	}
+}
+
+// TestPhaseJSONOmitEmpty verifies that optional Phase fields are absent from JSON when empty.
+func TestPhaseJSONOmitEmpty(t *testing.T) {
+	phase := Phase{ID: "d4e5f6a7"}
+
+	data, err := json.Marshal(phase)
+	if err != nil {
+		t.Fatalf("json.Marshal: %v", err)
+	}
+
+	var m map[string]any
+	if err := json.Unmarshal(data, &m); err != nil {
+		t.Fatalf("json.Unmarshal: %v", err)
+	}
+
+	// ID must always be present.
+	if _, ok := m["id"]; !ok {
+		t.Errorf("expected key %q in JSON, but missing", "id")
+	}
+
+	// Optional fields must be absent when empty.
+	for _, key := range []string{"name", "description"} {
+		if _, ok := m[key]; ok {
+			t.Errorf("unexpected key %q in JSON when field is empty", key)
+		}
+	}
+}
+
+// TestSectionJSONOmitEmpty verifies that optional Section fields are absent from JSON when empty.
+func TestSectionJSONOmitEmpty(t *testing.T) {
+	section := Section{ID: "b8c9d0e1", PhaseID: "d4e5f6a7"}
+
+	data, err := json.Marshal(section)
+	if err != nil {
+		t.Fatalf("json.Marshal: %v", err)
+	}
+
+	var m map[string]any
+	if err := json.Unmarshal(data, &m); err != nil {
+		t.Fatalf("json.Unmarshal: %v", err)
+	}
+
+	// ID and PhaseID must always be present.
+	for _, key := range []string{"id", "phaseId"} {
+		if _, ok := m[key]; !ok {
+			t.Errorf("expected key %q in JSON, but missing", key)
+		}
+	}
+
+	// Optional fields must be absent when empty.
+	for _, key := range []string{"name", "description"} {
+		if _, ok := m[key]; ok {
+			t.Errorf("unexpected key %q in JSON when field is empty", key)
+		}
+	}
+}
+
+// TestTaskJSONOmitEmpty verifies that optional Task fields are absent from JSON when empty.
+func TestTaskJSONOmitEmpty(t *testing.T) {
+	task := Task{
+		ID:          "a3f7b2c1",
+		Subject:     "Do something",
+		Status:      StatusPending,
+		LastUpdated: time.Date(2026, 3, 10, 14, 22, 0, 0, time.UTC),
+	}
+
+	data, err := json.Marshal(task)
+	if err != nil {
+		t.Fatalf("json.Marshal: %v", err)
+	}
+
+	var m map[string]any
+	if err := json.Unmarshal(data, &m); err != nil {
+		t.Fatalf("json.Unmarshal: %v", err)
+	}
+
+	// Required fields must be present.
+	for _, key := range []string{"id", "subject", "status", "lastUpdated"} {
+		if _, ok := m[key]; !ok {
+			t.Errorf("expected key %q in JSON, but missing", key)
+		}
+	}
+
+	// Optional fields must be absent when empty.
+	for _, key := range []string{"phaseId", "sectionId", "notes"} {
+		if _, ok := m[key]; ok {
+			t.Errorf("unexpected key %q in JSON when field is empty", key)
+		}
+	}
+}
+
+// TestTaskJSONRoundTrip verifies JSON serialization and deserialization of a Task with all fields.
+func TestTaskJSONRoundTrip(t *testing.T) {
+	original := Task{
+		ID:          "a3f7b2c1",
+		Subject:     "Implement stream-JSON output parsing",
+		Status:      StatusCompleted,
+		PhaseID:     "d4e5f6a7",
+		SectionID:   "b8c9d0e1",
+		Notes:       "Scans stdout line-by-line.",
+		LastUpdated: time.Date(2026, 3, 10, 14, 22, 0, 0, time.UTC),
+	}
+
+	data, err := json.Marshal(original)
+	if err != nil {
+		t.Fatalf("json.Marshal: %v", err)
+	}
+
+	var got Task
+	if err := json.Unmarshal(data, &got); err != nil {
+		t.Fatalf("json.Unmarshal: %v", err)
+	}
+
+	if got.ID != original.ID {
+		t.Errorf("ID: got %q, want %q", got.ID, original.ID)
+	}
+	if got.Subject != original.Subject {
+		t.Errorf("Subject: got %q, want %q", got.Subject, original.Subject)
+	}
+	if got.Status != original.Status {
+		t.Errorf("Status: got %q, want %q", got.Status, original.Status)
+	}
+	if got.PhaseID != original.PhaseID {
+		t.Errorf("PhaseID: got %q, want %q", got.PhaseID, original.PhaseID)
+	}
+	if got.SectionID != original.SectionID {
+		t.Errorf("SectionID: got %q, want %q", got.SectionID, original.SectionID)
+	}
+	if got.Notes != original.Notes {
+		t.Errorf("Notes: got %q, want %q", got.Notes, original.Notes)
+	}
+	if !got.LastUpdated.Equal(original.LastUpdated) {
+		t.Errorf("LastUpdated: got %v, want %v", got.LastUpdated, original.LastUpdated)
+	}
+}
+
+// TestTaskListJSONOmitEmpty verifies that optional TaskList fields are absent from JSON when empty.
+func TestTaskListJSONOmitEmpty(t *testing.T) {
+	list := TaskList{
+		Tasks:       []Task{},
+		Version:     "1.0",
+		LastUpdated: time.Date(2026, 3, 10, 15, 0, 0, 0, time.UTC),
+	}
+
+	data, err := json.Marshal(list)
+	if err != nil {
+		t.Fatalf("json.Marshal: %v", err)
+	}
+
+	var m map[string]any
+	if err := json.Unmarshal(data, &m); err != nil {
+		t.Fatalf("json.Unmarshal: %v", err)
+	}
+
+	// Required fields must be present.
+	for _, key := range []string{"tasks", "version", "lastUpdated"} {
+		if _, ok := m[key]; !ok {
+			t.Errorf("expected key %q in JSON, but missing", key)
+		}
+	}
+
+	// Optional fields must be absent when empty.
+	for _, key := range []string{"name", "description", "phases", "sections"} {
+		if _, ok := m[key]; ok {
+			t.Errorf("unexpected key %q in JSON when field is empty", key)
+		}
+	}
+}
+
+// TestGenerateID verifies that generateID returns an 8-character lowercase hex string.
+func TestGenerateID(t *testing.T) {
+	hexPattern := regexp.MustCompile(`^[0-9a-f]{8}$`)
+
+	id := generateID()
+	if !hexPattern.MatchString(id) {
+		t.Errorf("generateID() = %q, want 8-char lowercase hex", id)
+	}
+}
+
+// TestGenerateIDUnique verifies that generateID produces unique values.
+func TestGenerateIDUnique(t *testing.T) {
+	seen := make(map[string]bool)
+	for i := range 100 {
+		id := generateID()
+		if seen[id] {
+			t.Errorf("generateID() returned duplicate value %q on iteration %d", id, i)
+		}
+		seen[id] = true
+	}
+}
diff --git a/main.go b/main.go
index b860891..b426161 100644
--- a/main.go
+++ b/main.go
@@ -1,251 +1,145 @@
 // Lorah - Simple infinite loop harness for Claude Code
 //
-// Usage: lorah PROMPT.md [claude-flags...]
+// Usage: lorah <command> [arguments]
 //
-// Runs an infinite loop that executes Claude CLI with stream-JSON output,
-// parses messages, formats output with colors, and retries on errors.
+// Runs Claude Code CLI in a continuous loop with formatted output.
 package main
 
 import (
-	"bufio"
-	"context"
-	"encoding/json"
 	"fmt"
-	"io"
 	"os"
-	"os/exec"
-	"os/signal"
-	"strings"
-	"syscall"
-	"time"
+
+	"github.com/cpplain/lorah/internal/loop"
+	"github.com/cpplain/lorah/internal/task"
 )
 
 // Version is set via ldflags during build. Default is "dev" for local builds.
 var Version = "dev"
 
-const (
-	colorReset = "\033[0m"
-	colorGreen = "\033[32m"
-	colorBlue  = "\033[34m"
-	colorBold  = "\033[1m"
-	colorRed   = "\033[31m"
+func printUsage() {
+	fmt.Fprint(os.Stderr, `Usage: lorah <command> [arguments]
 
-	maxBufferSize = 1024 * 1024 // 1MB buffer for JSON parsing
-	retryDelay    = 5 * time.Second
-)
+Simple infinite-loop harness for Claude Code.
 
-// printSection outputs a labeled section with optional content.
-func printSection(label, color, content string) {
-	fmt.Printf("%s⏺%s %s%s%s\n", color, colorReset, colorBold, label, colorReset)
-	if content != "" {
-		content = strings.TrimSpace(content)
-		fmt.Printf("%s\n", content)
-	}
-	fmt.Println()
-}
+Commands:
+  run     Run Claude Code CLI in an infinite loop
+  task    Manage tasks
 
-func main() {
-	// Handle --version / -version / -V
-	if len(os.Args) == 2 && (os.Args[1] == "--version" || os.Args[1] == "-version" || os.Args[1] == "-V") {
-		fmt.Printf("lorah %s\n", Version)
-		os.Exit(0)
-	}
+Flags:
+  -V, --version    Print version and exit
+  -h, --help       Show this help message
+
+Run 'lorah <command> --help' for command-specific help.
+`)
+}
 
-	// Handle --help / -help / -h or no args
-	if len(os.Args) < 2 || os.Args[1] == "--help" || os.Args[1] == "-help" || os.Args[1] == "-h" {
-		fmt.Fprint(os.Stderr, `Usage: lorah <prompt-file> [claude-flags...]
+func printRunUsage() {
+	fmt.Fprint(os.Stderr, `Usage: lorah run <prompt-file> [claude-flags...]
 
-Simple infinite-loop harness for Claude Code.
-Runs Claude CLI in a continuous loop with formatted output.
+Run Claude Code CLI in a continuous loop with formatted output.
+Retries automatically on error with a 5-second delay.
 
 Arguments:
-  <prompt-file>      Path to prompt file (required, first argument)
-  [claude-flags...]  Flags passed directly to claude CLI (optional)
+  <prompt-file>      Path to prompt file (required)
+  [claude-flags...]  Flags passed directly to claude CLI
 
 Examples:
-  lorah prompt.md
-  lorah task.txt --settings .lorah/settings.json
-  lorah instructions.md --model opus --max-turns 50
+  lorah run prompt.md
+  lorah run task.txt --settings .lorah/settings.json
+  lorah run instructions.md --model claude-opus-4-6 --max-turns 50
 
 Flags:
-  -V, --version      Print version and exit
-  -h, --help         Show this help message
+  -h, --help    Show this help message
 `)
-		os.Exit(1)
-	}
+}
 
-	promptFile := os.Args[1]
-	claudeFlags := os.Args[2:]
-
-	// Handle Ctrl+C gracefully
-	ctx, cancel := context.WithCancel(context.Background())
-	defer cancel()
-
-	sigCh := make(chan os.Signal, 1)
-	signal.Notify(sigCh, os.Interrupt, syscall.SIGTERM)
-	go func() {
-		<-sigCh
-		fmt.Println()
-		printSection("Lorah", colorBlue, "Received interrupt, shutting down...")
-		cancel()
-		os.Exit(0)
-	}()
-
-	// Infinite loop
-	iteration := 0
-	for {
-		iteration++
-		printSection("Lorah", colorBlue, "Starting loop...")
-
-		if err := runClaude(ctx, promptFile, claudeFlags); err != nil {
-			fmt.Fprintf(os.Stderr, "\n%s⏺ %sError%s\n", colorRed, colorBold, colorReset)
-			fmt.Fprintf(os.Stderr, "%v\n\n", err)
-			fmt.Fprintf(os.Stderr, "Retrying in %v...\n\n", retryDelay)
-			time.Sleep(retryDelay)
-			continue
-		}
+func printTaskUsage() {
+	fmt.Fprint(os.Stderr, `Usage: lorah task <subcommand> [args...] [flags...]
 
-		// Success - continue immediately to next iteration
-		printSection("Lorah", colorBlue, "Loop completed successfully")
-	}
+Manage tasks stored in tasks.json.
+
+Subcommands:
+  list        List tasks
+  get         Get task details
+  create      Create a new task
+  update      Update a task
+  delete      Delete a task
+  export      Export tasks to markdown
+
+Flags:
+  -h, --help    Show this help message
+
+Run 'lorah task <subcommand> --help' for subcommand-specific help.
+`)
 }
 
-// runClaude executes a single Claude CLI session with the prompt file piped to stdin.
-func runClaude(ctx context.Context, promptFile string, flags []string) error {
-	// Open prompt file to pipe as stdin
-	file, err := os.Open(promptFile)
-	if err != nil {
-		return fmt.Errorf("opening prompt file: %w", err)
+// route dispatches CLI arguments to the appropriate handler and returns an exit code.
+func route(args []string, version string, runFn func(string, []string), taskFn func([]string) error) int {
+	if len(args) == 0 {
+		printUsage()
+		return 1
 	}
-	defer file.Close()
 
-	// Build claude command
-	args := []string{
-		"-p",
-		"--output-format", "stream-json",
-		"--verbose",
-	}
-	args = append(args, flags...) // Add user-provided flags
+	switch args[0] {
+	case "--version", "-version", "-V":
+		fmt.Printf("lorah %s\n", version)
+		return 0
 
-	cmd := exec.CommandContext(ctx, "claude", args...)
-	cmd.Stdin = file // Pipe prompt file contents to stdin
-	cmd.Stderr = os.Stderr
-	cmd.Env = os.Environ()
+	case "--help", "-help", "-h":
+		printUsage()
+		return 0
 
-	stdout, err := cmd.StdoutPipe()
-	if err != nil {
-		return fmt.Errorf("creating stdout pipe: %w", err)
-	}
+	case "run":
+		runArgs := args[1:]
+		if len(runArgs) == 0 {
+			printRunUsage()
+			return 1
+		}
+		if runArgs[0] == "--help" || runArgs[0] == "-help" || runArgs[0] == "-h" {
+			printRunUsage()
+			return 0
+		}
+		promptFile := runArgs[0]
+		claudeFlags := runArgs[1:]
+		runFn(promptFile, claudeFlags)
+		return 0
+
+	case "task":
+		taskArgs := args[1:]
+		if len(taskArgs) == 0 {
+			printTaskUsage()
+			return 1
+		}
+		if taskArgs[0] == "--help" || taskArgs[0] == "-help" || taskArgs[0] == "-h" {
+			printTaskUsage()
+			return 0
+		}
+		if err := taskFn(taskArgs); err != nil {
+			fmt.Fprintf(os.Stderr, "%v\n", err)
+			return 1
+		}
+		return 0
 
-	if err := cmd.Start(); err != nil {
-		return fmt.Errorf("starting claude CLI: %w", err)
+	default:
+		fmt.Fprintf(os.Stderr, "Unknown command: %s\n", args[0])
+		printUsage()
+		return 1
 	}
+}
 
-	// Print formatted output in real-time
-	printMessages(stdout)
+func runCmd(promptFile string, claudeFlags []string) {
+	loop.Run(promptFile, claudeFlags)
+}
 
-	if err := cmd.Wait(); err != nil {
-		return fmt.Errorf("claude CLI exited with error: %w", err)
+func taskCmd(args []string) error {
+	storage := task.NewJSONStorage("tasks.json")
+	code := task.HandleTask(args, os.Stdout, storage)
+	if code != 0 {
+		return fmt.Errorf("task command failed")
 	}
-
 	return nil
 }
 
-// printMessages reads stream-JSON from r and prints formatted output.
-func printMessages(r io.Reader) {
-	scanner := bufio.NewScanner(r)
-	scanner.Buffer(make([]byte, 0, 4096), maxBufferSize)
-
-	for scanner.Scan() {
-		line := scanner.Text()
-		if line == "" {
-			continue
-		}
-
-		var msg map[string]any
-		if err := json.Unmarshal([]byte(line), &msg); err != nil {
-			// Skip malformed JSON silently for forward compatibility
-			continue
-		}
-
-		msgType, _ := msg["type"].(string)
-
-		switch msgType {
-		case "assistant":
-			msgData, ok := msg["message"].(map[string]any)
-			if !ok {
-				continue
-			}
-
-			contentArray, ok := msgData["content"].([]any)
-			if !ok {
-				continue
-			}
-
-			for _, item := range contentArray {
-				block, ok := item.(map[string]any)
-				if !ok {
-					continue
-				}
-
-				blockType, _ := block["type"].(string)
-
-				switch blockType {
-				case "text":
-					text, _ := block["text"].(string)
-					printSection("Claude", colorBlue, text)
-
-				case "thinking":
-					thinking, _ := block["thinking"].(string)
-					printSection("Claude (thinking)", colorBlue, thinking)
-
-				case "tool_use":
-					name, _ := block["name"].(string)
-					if name == "" {
-						continue
-					}
-
-					// Format tool name to title case
-					toolName := strings.ToUpper(name[:1]) + strings.ToLower(name[1:])
-
-					// Extract relevant input parameter for display
-					var content string
-					if input, ok := block["input"].(map[string]any); ok {
-						switch name {
-						case "Bash":
-							content, _ = input["command"].(string)
-						case "Read", "Edit", "Write":
-							content, _ = input["file_path"].(string)
-						case "Grep", "Glob":
-							content, _ = input["pattern"].(string)
-						case "WebFetch":
-							content, _ = input["url"].(string)
-						case "Task":
-							content, _ = input["description"].(string)
-						case "Agent":
-							content, _ = input["prompt"].(string)
-						}
-					}
-
-					// Truncate to 1 line if longer
-					if content != "" {
-						lines := strings.Split(content, "\n")
-						if len(lines) > 1 {
-							content = strings.Join(lines[:1], "\n") + fmt.Sprintf("\n... +%d lines", len(lines)-1)
-						}
-					}
-
-					printSection(toolName, colorGreen, content)
-				}
-			}
-
-		case "result":
-			isError, _ := msg["is_error"].(bool)
-			if isError {
-				result, _ := msg["result"].(string)
-				fmt.Println()
-				printSection("Result (error)", colorRed, result)
-			}
-		}
-	}
+func main() {
+	os.Exit(route(os.Args[1:], Version, runCmd, taskCmd))
 }
diff --git a/main_test.go b/main_test.go
new file mode 100644
index 0000000..52e6ec1
--- /dev/null
+++ b/main_test.go
@@ -0,0 +1,131 @@
+package main
+
+import (
+	"io"
+	"os"
+	"strings"
+	"testing"
+)
+
+// captureOutput redirects os.Stdout and os.Stderr, runs fn, then restores them.
+// Returns captured stdout and stderr as strings.
+func captureOutput(fn func()) (stdout, stderr string) {
+	oldStdout := os.Stdout
+	rOut, wOut, _ := os.Pipe()
+	os.Stdout = wOut
+
+	oldStderr := os.Stderr
+	rErr, wErr, _ := os.Pipe()
+	os.Stderr = wErr
+
+	fn()
+
+	wOut.Close()
+	wErr.Close()
+
+	outBytes, _ := io.ReadAll(rOut)
+	errBytes, _ := io.ReadAll(rErr)
+
+	os.Stdout = oldStdout
+	os.Stderr = oldStderr
+
+	return string(outBytes), string(errBytes)
+}
+
+func TestRoute_Version(t *testing.T) {
+	for _, flag := range []string{"--version", "-version", "-V"} {
+		t.Run(flag, func(t *testing.T) {
+			var code int
+			stdout, _ := captureOutput(func() {
+				code = route([]string{flag}, "1.2.3", nil, nil)
+			})
+			if code != 0 {
+				t.Errorf("expected exit 0, got %d", code)
+			}
+			if !strings.Contains(stdout, "lorah 1.2.3") {
+				t.Errorf("expected %q in stdout, got %q", "lorah 1.2.3", stdout)
+			}
+		})
+	}
+}
+
+func TestRoute_Help(t *testing.T) {
+	for _, flag := range []string{"--help", "-help", "-h"} {
+		t.Run(flag, func(t *testing.T) {
+			var code int
+			_, stderr := captureOutput(func() {
+				code = route([]string{flag}, "dev", nil, nil)
+			})
+			if code != 0 {
+				t.Errorf("expected exit 0, got %d", code)
+			}
+			if !strings.Contains(stderr, "Usage:") {
+				t.Errorf("expected usage in stderr, got %q", stderr)
+			}
+		})
+	}
+}
+
+// TestRoute_NoArgs verifies that no arguments prints usage to stderr and exits 1.
+// This is distinct from --help which exits 0 (per cli.md §3).
+func TestRoute_NoArgs(t *testing.T) {
+	var code int
+	_, stderr := captureOutput(func() {
+		code = route([]string{}, "dev", nil, nil)
+	})
+	if code != 1 {
+		t.Errorf("expected exit 1, got %d", code)
+	}
+	if !strings.Contains(stderr, "Usage:") {
+		t.Errorf("expected usage in stderr, got %q", stderr)
+	}
+}
+
+func TestRoute_Run(t *testing.T) {
+	var calledFile string
+	var calledFlags []string
+	runFn := func(file string, flags []string) {
+		calledFile = file
+		calledFlags = flags
+	}
+
+	code := route([]string{"run", "prompt.md", "--max-turns", "50"}, "dev", runFn, nil)
+	if code != 0 {
+		t.Errorf("expected exit 0, got %d", code)
+	}
+	if calledFile != "prompt.md" {
+		t.Errorf("expected prompt file %q, got %q", "prompt.md", calledFile)
+	}
+	if len(calledFlags) != 2 || calledFlags[0] != "--max-turns" || calledFlags[1] != "50" {
+		t.Errorf("unexpected flags: %v", calledFlags)
+	}
+}
+
+func TestRoute_Task(t *testing.T) {
+	var calledArgs []string
+	taskFn := func(args []string) error {
+		calledArgs = args
+		return nil
+	}
+
+	code := route([]string{"task", "list"}, "dev", nil, taskFn)
+	if code != 0 {
+		t.Errorf("expected exit 0, got %d", code)
+	}
+	if len(calledArgs) != 1 || calledArgs[0] != "list" {
+		t.Errorf("unexpected args: %v", calledArgs)
+	}
+}
+
+func TestRoute_UnknownCommand(t *testing.T) {
+	var code int
+	_, stderr := captureOutput(func() {
+		code = route([]string{"unknown"}, "dev", nil, nil)
+	})
+	if code != 1 {
+		t.Errorf("expected exit 1, got %d", code)
+	}
+	if !strings.Contains(stderr, "Unknown command: unknown") {
+		t.Errorf("expected error message in stderr, got %q", stderr)
+	}
+}