Rethink decisions & todos: make them legible and worth using

[claude]

🤖 Agent-Generated PR

Closes #10
Agent Used: Claude Code (claude-sonnet-4-6)
Complexity: high

---

Summary

Redesigns how @decision and @todo are captured, surfaced, and closed so they're first-class and worth using. Adds dedicated capture commands, crisp rendering with date/statement/citation format, proactive surfacing in journal today, and resolution notes on journal done.

Implementation Notes

• Followed the approved plan in docs/plans/2026-06-19-010-feature-decisions-todos-legibility-plan.md (copied from plan/issue-10 branch).
• Zero changes to internal/note parsing — full backward compatibility; existing @decision/@todo/@done blocks continue to parse and surface correctly.
• decisionsStatement() extracts the statement from the snippet by splitting on Rationale: — works for both new structured entries and legacy opaque blocks (first line of collapsed body).
• completeTodo signature updated from (ctx, cfg, e, ref, logf) to (ctx, cfg, e, ref, resolution, logf) — TUI, CLI, and MCP callers all updated.
• todayReport.Decisions is an additive JSON field — existing MCP consumers see it as an optional field, no breaking change.
• Supersedence tracking (--supersedes flag, --active filter) deferred as a follow-up per plan.

Changes

• cmd/decide.go (new) — journal decide "<statement>" [--rationale text] [--project slug]
• cmd/todo.go (new) — journal todo "<action>" [--project slug]
• cmd/listing.go — renderDecisions(), decisionsStatement(), decisionsRationale(), dateFromPath() helpers; decisionsCmd uses renderDecisions instead of generic renderResults
• cmd/done.go — doneCmd accepts 1–2 args; completeTodo gains resolution string parameter; resolution appended as Resolution: <text> within the block
• cmd/show.go — todayReport.Decisions []Result; gatherToday queries top-5 decisions from last 2w; composeToday adds "Recent decisions" section
• cmd/mcp.go — doneInput.Resolution field; mcpDone passes resolution through; done tool description updated; mcpToday gains decisions automatically via todayReport
• cmd/tui.go — updated completeTodo call signature

Testing

Automated:

• Unit tests added/updated
• Integration tests added/updated
• All existing tests pass (make test → all green)

Manual testing performed:

• Build verified (go build ./...)
• make fmt vet clean
• Test coverage: TestDecideWriteDecisionBlock, TestTodoWritesTodoBlock, TestDecisionsStatement, TestRenderDecisionsTextMode, TestCompleteTodoWithResolutionNote, TestGatherTodayIncludesRecentDecisions, TestMCPTodayIncludesDecisions, TestMCPDoneWithResolution, TestDecisionsLegacyOpaqueBlock

---

Review Checklist

Correctness

• Code actually solves the issue
• Acceptance criteria are met
• Edge cases handled (empty statement, stale index, legacy opaque blocks, old decisions excluded from today)

Code Quality

• Follows existing codebase patterns (capture() reuse, autoCommitCapture, cobra command structure)
• Follows project coding standards
• Naming conventions consistent
• No unnecessary complexity
• Comments where needed

Security

• Input validation present (empty statement → error via capture())
• No exposed secrets or credentials

Tests

• Tests actually test behavior (not just coverage)
• Edge cases covered (ambiguous refs, missing todos, stale index, legacy blocks, old decisions)
• Failure modes tested

---

Reviewer Notes

• The decisionsStatement(snippet) helper splits on Rationale: to separate statement from rationale in the whitespace-collapsed snippet. This is simple and robust for structured entries; for legacy opaque blocks it just returns the whole snippet (no Rationale: present).
• The 2-week window for decisions in journal today is hardcoded as 14 * 24 * time.Hour — the plan didn't call for a flag, and we can add one as a follow-up.
• journal decide and journal todo are distinct from journal todos (the listing command) — cobra handles the disambiguation correctly since todo and todos are different strings.

[claude]

Retro: no durable lesson (merged clean / one-off).