@scardis/omnifocus-mcp 0.1.0

package/openspec/changes/archive/2026-04-09-tag-crud/tasks.md

@@ -0,0 +1,41 @@
+## 1. Snippets (src/snippets/)
+
+- [x] 1.1 `create_tag.js`: accept `{name, parentTagId?}`; if `parentTagId` provided resolve parent tag by ID and throw `NotFoundError` if missing; create `new Tag(name)` or `new Tag(name, parentTag)`; return full tag detail envelope
+- [x] 1.2 `edit_tag.js`: accept `{id, name?, status?}`; resolve tag by ID; apply only provided fields; map `status` string to `Tag.Status` enum member; return updated full tag detail envelope
+- [x] 1.3 `delete_tag.js`: accept `{id}`; resolve tag by ID; call `deleteObject(tag)` (OmniFocus handles child tag and association cleanup automatically); return `{ok: true, data: {id}}`
+
+## 2. Snippet allowlist
+
+- [x] 2.1 Add `create_tag`, `edit_tag`, `delete_tag` to `ALLOWED_SNIPPETS` in `src/runtime/snippetLoader.ts`
+
+## 3. Schemas (src/schemas/shapes.ts)
+
+- [x] 3.1 Define `CreateTagInput` zod schema: `{name: z.string().min(1), parentTagId: IdSchema.optional()}`
+- [x] 3.2 Define `EditTagInput` zod schema: `{id: IdSchema, name: z.string().min(1).optional(), status: TagStatus.optional()}`; add `.refine()` requiring at least one of `name` or `status`
+
+## 4. Tool handlers (src/tools/)
+
+- [x] 4.1 `createTag.ts`: validate input with `CreateTagInput`; invoke `runSnippet("create_tag", args)`; validate result against `TagDetail`; return
+- [x] 4.2 `editTag.ts`: validate input with `EditTagInput`; invoke `runSnippet("edit_tag", args)`; validate result against `TagDetail`; return
+- [x] 4.3 `deleteTag.ts`: input `{id: IdSchema}`; tool description MUST state the AI should confirm with the user before invoking and note that child tags are also permanently deleted; invoke `runSnippet("delete_tag", {id})`; return confirmation
+
+## 5. Server registration
+
+- [x] 5.1 Export all three new tool definitions from `src/tools/index.ts`
+
+## 6. Unit tests (test/unit/)
+
+- [x] 6.1 `schemas.editTag.test.ts`: valid inputs pass; empty object (neither name nor status) rejected by refine; invalid status enum rejected
+
+## 7. Integration tests (test/integration/)
+
+- [x] 7.1 `createTag.int.test.ts`: create top-level tag; create child tag; verify `path`, `parentId`, `childTagIds`
+- [x] 7.2 `editTag.int.test.ts`: rename a tag; put tag on hold; verify status and name
+- [x] 7.3 `deleteTag.int.test.ts`: delete a tag; verify subsequent `get_tag` returns not-found; verify child tags also gone
+
+## 8. Verification
+
+- [x] 8.1 `npm run typecheck` clean
+- [x] 8.2 `npm test` (unit suite) clean
+- [x] 8.3 Manually run integration suite; verify fixture cleanup
+- [ ] 8.4 Connect to Claude Desktop; exercise all three tools against a real database

package/openspec/changes/archive/2026-04-09-task-crud/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-04-09

package/openspec/changes/archive/2026-04-09-task-crud/design.md

@@ -0,0 +1,62 @@
+## Context
+
+The bootstrap change established the JXA→OmniJS bridge, snippet pattern, and result protocol. All five write tools follow those same patterns. The key question for writes is: what does OmniJS expose for creating and mutating tasks, and what are the edge cases?
+
+OmniJS task write operations:
+- `new Task(name, position)` — creates a task; `position` is a `Project` or `Task` (for subtasks)
+- `task.name = "..."` — property assignment for most scalar fields
+- `task.markComplete()` — dedicated method (not property assignment)
+- `task.drop()` — dedicated method
+- `deleteObject(task)` — permanent deletion
+- Tags: `task.addTag(tag)` / `task.removeTag(tag)` — manipulate by Tag object, not ID
+
+## Goals / Non-Goals
+
+**Goals:**
+- Expose create, edit, complete, drop, and delete for tasks
+- Support inbox tasks (no project), project tasks, and subtasks
+- Edit any subset of fields in one call (fat edit — no single-field tools)
+- Permanently delete with a tool description that instructs the AI to confirm before invoking
+
+**Non-Goals:**
+- Moving tasks between projects/containers (separate `move-operations` change)
+- Recurrence rules (separate `recurrence` change)
+- Batch operations (separate change)
+
+## Decisions
+
+### Decision 1: Tag manipulation by ID, resolved inside the snippet
+
+Tags are assigned via `task.addTag(tagObject)` / `task.removeTag(tagObject)`, which require a live `Tag` object. The snippet will receive tag IDs and resolve them via `flattenedTags.find(t => t.id.primaryKey === id)` inline. This keeps the bridge contract clean (IDs only) without requiring a separate resolution round-trip.
+
+**Alternative considered:** Accept tag names. Rejected — names are ambiguous; IDs are stable.
+
+### Decision 2: `edit_task` replaces tags, not merges
+
+When `tagIds` is provided to `edit_task`, the snippet replaces the task's full tag set (remove all, add new). When `tagIds` is omitted, tags are untouched. This is the least surprising contract: callers who want to add one tag still need to pass the full desired set, but they can read it from `get_task` first.
+
+**Alternative considered:** Separate `add_tags` / `remove_tags` fields. Rejected — more surface area with no material benefit given that `get_task` is cheap.
+
+### Decision 3: `create_task` placement via optional `projectId` and `parentTaskId`
+
+- Both omitted → inbox
+- `projectId` only → task added to project root
+- `parentTaskId` only → subtask; inherits project from parent
+- Both provided → error (ambiguous placement; caller must choose)
+
+This mirrors how OmniFocus itself treats task placement.
+
+### Decision 4: `complete_task` and `drop_task` as separate tools from `edit_task`
+
+Status transitions in OmniJS require method calls (`markComplete()`, `drop()`), not property assignment. Exposing them as dedicated tools makes the intent unambiguous and avoids a complex status-to-method dispatch inside `edit_task`. It also makes tool descriptions cleaner for the LLM.
+
+### Decision 5: `delete_task` tool description as the confirmation guardrail
+
+The server executes `deleteObject(task)` unconditionally when called. The confirmation requirement is enforced through the MCP tool description, which instructs the AI to ask the user explicitly before invoking this tool. This is consistent with how MCP tool descriptions guide AI behavior.
+
+## Risks / Trade-offs
+
+- **Partial edit with bad field value** → OmniJS will throw; the error envelope propagates back as an `ExecutionError`. No partial writes occur because OmniJS is synchronous within `evaluateJavascript`.
+- **Tag ID not found during edit** → Snippet should throw a descriptive `NotFoundError` for the missing tag ID, not silently skip it.
+- **Inbox placement** → `new Task(name, inbox)` requires passing the `inbox` object. In OmniJS the inbox is accessible as `inbox` (bare global). Verified pattern from the read-side exploration.
+- **deleteObject on a task with subtasks** → OmniJS deletes the task and all subtasks. Tool description should note this.

package/openspec/changes/archive/2026-04-09-task-crud/proposal.md

@@ -0,0 +1,29 @@
+## Why
+
+The bootstrap change delivered read-only task access. Callers can observe tasks but cannot create, modify, complete, drop, or delete them — making the server unsuitable for any workflow that involves acting on tasks, not just reading them.
+
+## What Changes
+
+- Add `create_task` tool: create a task in a project, as a subtask, or in the inbox
+- Add `edit_task` tool: modify any subset of a task's scalar fields and tag assignments in a single call
+- Add `complete_task` tool: mark a task complete
+- Add `drop_task` tool: mark a task dropped
+- Add `delete_task` tool: permanently delete a task (tool description instructs the AI to confirm with the user before invoking)
+
+## Capabilities
+
+### New Capabilities
+
+- `task-write`: Create, edit, complete, drop, and permanently delete OmniFocus tasks
+
+### Modified Capabilities
+
+- `task-management`: Extend existing spec to add write requirements alongside the existing read requirements
+
+## Impact
+
+- 5 new MCP tools registered in `src/server.ts`
+- 5 new tool handler files in `src/tools/`
+- 5 new OmniJS snippets in `src/snippets/`
+- `ALLOWED_SNIPPETS` allowlist in `src/runtime/snippetLoader.ts` must be extended
+- Integration tests will mutate real OmniFocus data (scoped to fixture folder per existing pattern)

package/openspec/changes/archive/2026-04-09-task-crud/specs/task-management/spec.md

@@ -0,0 +1,17 @@
+## MODIFIED Requirements
+
+### Requirement: Get task by ID
+
+The system SHALL provide a `get_task` tool that accepts `{id: string}` and returns the full detail record of the named task, including `{id, name, note, status, flagged, deferDate, dueDate, completionDate, estimatedMinutes, containerId, containerType, tagIds, parentTaskId}`. The `parentTaskId` field SHALL be `null` for top-level tasks and SHALL contain the parent task's `id.primaryKey` for subtasks. If no task exists with that ID, the tool SHALL return a structured not-found error.
+
+#### Scenario: Existing task returns full detail
+- **WHEN** `get_task` is called with the ID of an existing task
+- **THEN** the tool returns the task's full detail record including all scalar fields, the list of tag IDs assigned to it, and `parentTaskId`
+
+#### Scenario: Subtask includes parentTaskId
+- **WHEN** `get_task` is called with the ID of a subtask
+- **THEN** the returned record includes `parentTaskId` set to the parent task's stable ID
+
+#### Scenario: Missing task returns not-found error
+- **WHEN** `get_task` is called with an ID that does not correspond to any task
+- **THEN** the tool returns a structured error with a not-found code and does not throw an unhandled exception

package/openspec/changes/archive/2026-04-09-task-crud/specs/task-write/spec.md

@@ -0,0 +1,89 @@
+## ADDED Requirements
+
+### Requirement: Create task
+
+The system SHALL provide a `create_task` tool that creates a new OmniFocus task and returns its full detail record. The tool SHALL accept `{name: string, note?: string, flagged?: boolean, deferDate?: string, dueDate?: string, estimatedMinutes?: number, projectId?: string, parentTaskId?: string, tagIds?: string[]}`. Placement SHALL be determined as follows: if both `projectId` and `parentTaskId` are provided the tool SHALL return an error; if only `projectId` is provided the task is placed at the project root; if only `parentTaskId` is provided the task is created as a subtask inheriting its parent's project; if neither is provided the task is placed in the inbox.
+
+#### Scenario: Create inbox task
+- **WHEN** `create_task` is called with `{name: "Buy milk"}` and no `projectId` or `parentTaskId`
+- **THEN** the tool creates the task in the OmniFocus inbox and returns its full detail record including a stable `id`
+
+#### Scenario: Create task in a project
+- **WHEN** `create_task` is called with `{name: "Write tests", projectId: "abc123"}`
+- **THEN** the tool creates the task at the root of the specified project and returns its full detail record
+
+#### Scenario: Create subtask
+- **WHEN** `create_task` is called with `{name: "Review PR", parentTaskId: "xyz789"}`
+- **THEN** the tool creates the task as a child of the specified parent task and returns its full detail record
+
+#### Scenario: Ambiguous placement is rejected
+- **WHEN** `create_task` is called with both `projectId` and `parentTaskId`
+- **THEN** the tool returns a validation error before any snippet executes
+
+#### Scenario: Non-existent project returns not-found error
+- **WHEN** `create_task` is called with a `projectId` that does not correspond to any project
+- **THEN** the tool returns a structured not-found error
+
+### Requirement: Edit task
+
+The system SHALL provide an `edit_task` tool that modifies an existing task and returns its updated full detail record. The tool SHALL accept `{id: string}` plus any subset of `{name?: string, note?: string, flagged?: boolean, deferDate?: string | null, dueDate?: string | null, estimatedMinutes?: number | null, tagIds?: string[]}`. Fields omitted from the call SHALL be left unchanged. When `tagIds` is provided it SHALL replace the task's entire tag set; when omitted, tags SHALL be unchanged. Passing `null` for a date or `estimatedMinutes` SHALL clear the field.
+
+#### Scenario: Edit a single field
+- **WHEN** `edit_task` is called with `{id: "abc123", flagged: true}`
+- **THEN** only the `flagged` field is changed; all other fields retain their previous values
+
+#### Scenario: Replace tag set
+- **WHEN** `edit_task` is called with `{id: "abc123", tagIds: ["t1", "t2"]}`
+- **THEN** the task's tags are set to exactly `["t1", "t2"]`, replacing any previously assigned tags
+
+#### Scenario: Clear a date field
+- **WHEN** `edit_task` is called with `{id: "abc123", dueDate: null}`
+- **THEN** the task's due date is cleared
+
+#### Scenario: Non-existent task returns not-found error
+- **WHEN** `edit_task` is called with an ID that does not correspond to any task
+- **THEN** the tool returns a structured not-found error
+
+#### Scenario: Non-existent tag ID returns not-found error
+- **WHEN** `edit_task` is called with a `tagIds` array containing an ID that does not correspond to any tag
+- **THEN** the tool returns a structured not-found error and the task is not modified
+
+### Requirement: Complete task
+
+The system SHALL provide a `complete_task` tool that marks an existing task complete using OmniJS `markComplete()` and returns the task's updated full detail record.
+
+#### Scenario: Complete an existing task
+- **WHEN** `complete_task` is called with the ID of an available task
+- **THEN** the task's status becomes `"complete"` and the tool returns the updated detail record
+
+#### Scenario: Non-existent task returns not-found error
+- **WHEN** `complete_task` is called with an ID that does not correspond to any task
+- **THEN** the tool returns a structured not-found error
+
+### Requirement: Drop task
+
+The system SHALL provide a `drop_task` tool that marks an existing task dropped using OmniJS `drop()` and returns the task's updated full detail record.
+
+#### Scenario: Drop an existing task
+- **WHEN** `drop_task` is called with the ID of an available task
+- **THEN** the task's status becomes `"dropped"` and the tool returns the updated detail record
+
+#### Scenario: Non-existent task returns not-found error
+- **WHEN** `drop_task` is called with an ID that does not correspond to any task
+- **THEN** the tool returns a structured not-found error
+
+### Requirement: Delete task
+
+The system SHALL provide a `delete_task` tool that permanently deletes a task and all its subtasks using OmniJS `deleteObject()`. The tool description SHALL instruct the AI to confirm with the user before invoking this tool, noting that deletion is permanent and includes all subtasks.
+
+#### Scenario: Delete an existing task
+- **WHEN** `delete_task` is called with the ID of an existing task
+- **THEN** the task and all its subtasks are permanently removed from OmniFocus and the tool returns a confirmation envelope
+
+#### Scenario: Delete task with subtasks removes all children
+- **WHEN** `delete_task` is called with the ID of a task that has subtasks
+- **THEN** the task and all descendant subtasks are deleted
+
+#### Scenario: Non-existent task returns not-found error
+- **WHEN** `delete_task` is called with an ID that does not correspond to any task
+- **THEN** the tool returns a structured not-found error

package/openspec/changes/archive/2026-04-09-task-crud/tasks.md

@@ -0,0 +1,55 @@
+## 1. Snippets (src/snippets/)
+
+- [x] 1.1 `create_task.js`: accept `{name, note?, flagged?, deferDate?, dueDate?, estimatedMinutes?, projectId?, parentTaskId?, tagIds?}`; resolve placement (inbox / project root / subtask); throw `ConflictError` if both `projectId` and `parentTaskId` provided; throw `NotFoundError` on missing project, parent task, or tag ID; return full task detail envelope
+- [x] 1.2 `edit_task.js`: accept `{id, name?, note?, flagged?, deferDate?, dueDate?, estimatedMinutes?, tagIds?}`; resolve task by ID; apply only provided fields; when `tagIds` present replace full tag set (remove all, add each by ID); pass `null` dates/estimatedMinutes to clear; return updated full detail envelope
+- [x] 1.3 `complete_task.js`: accept `{id}`; resolve task by ID; call `task.markComplete()`; return updated full detail envelope
+- [x] 1.4 `drop_task.js`: accept `{id}`; resolve task by ID; call `task.drop()`; return updated full detail envelope
+- [x] 1.5 `delete_task.js`: accept `{id}`; resolve task by ID; call `deleteObject(task)`; return `{ok: true, data: {id}}`
+
+## 2. Snippet allowlist
+
+- [x] 2.1 Add `create_task`, `edit_task`, `complete_task`, `drop_task`, `delete_task` to `ALLOWED_SNIPPETS` in `src/runtime/snippetLoader.ts`
+
+## 3. Schemas (src/schemas/shapes.ts)
+
+- [x] 3.1 Add `parentTaskId: z.string().nullable()` to `TaskDetail` schema
+- [x] 3.2 Define `CreateTaskInput` zod schema with all optional fields and the mutual-exclusion refinement for `projectId` + `parentTaskId`
+- [x] 3.3 Define `EditTaskInput` zod schema — `id` required, all other fields optional; date fields accept `string | null`; `estimatedMinutes` accepts `number | null`
+
+## 4. Tool handlers (src/tools/)
+
+- [x] 4.1 `createTask.ts`: validate input with `CreateTaskInput`; invoke `runSnippet("create_task", args)`; validate result against `TaskDetail`; return
+- [x] 4.2 `editTask.ts`: validate input with `EditTaskInput`; invoke `runSnippet("edit_task", args)`; validate result against `TaskDetail`; return
+- [x] 4.3 `completeTask.ts`: input `{id: IdSchema}`; invoke `runSnippet("complete_task", {id})`; validate result against `TaskDetail`; return
+- [x] 4.4 `dropTask.ts`: input `{id: IdSchema}`; invoke `runSnippet("drop_task", {id})`; validate result against `TaskDetail`; return
+- [x] 4.5 `deleteTask.ts`: input `{id: IdSchema}`; tool description MUST state the AI should confirm with the user before invoking and note that deletion is permanent and includes all subtasks; invoke `runSnippet("delete_task", {id})`; return confirmation
+
+## 5. Server registration
+
+- [x] 5.1 Export all five new tool definitions from `src/tools/index.ts`
+- [x] 5.2 Verify `src/server.ts` picks them up via the `allTools` barrel (no change needed if barrel is already dynamic)
+
+## 6. get_task update
+
+- [x] 6.1 Update `src/snippets/get_task.js` to include `parentTaskId` in the returned detail (`t.parentTask ? t.parentTask.id.primaryKey : null`)
+- [x] 6.2 Update `src/tools/getTask.ts` to validate against the updated `TaskDetail` schema
+
+## 7. Unit tests (test/unit/)
+
+- [x] 7.1 `schemas.createTask.test.ts`: valid inputs pass; both `projectId` + `parentTaskId` rejected; missing name rejected; null dates accepted in edit schema
+- [x] 7.2 `tools.deleteTask.test.ts`: verify tool description contains confirmation language
+
+## 8. Integration tests (test/integration/)
+
+- [x] 8.1 `createTask.int.test.ts`: create inbox task, verify returned ID; create project task, verify containerId; create subtask, verify parentTaskId
+- [x] 8.2 `editTask.int.test.ts`: edit name; edit flags; replace tag set; clear due date
+- [x] 8.3 `completeTask.int.test.ts`: complete a task, verify status = `"complete"`
+- [x] 8.4 `dropTask.int.test.ts`: drop a task, verify status = `"dropped"`
+- [x] 8.5 `deleteTask.int.test.ts`: delete a task, verify subsequent `get_task` returns not-found
+
+## 9. Verification
+
+- [x] 9.1 `npm run typecheck` clean
+- [x] 9.2 `npm test` (unit suite) clean
+- [x] 9.3 Manually run integration suite; verify fixture cleanup
+- [ ] 9.4 Connect to Claude Desktop; exercise all five tools against a real database

package/openspec/changes/archive/2026-04-09-task-filtering/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-04-09

package/openspec/changes/archive/2026-04-09-task-filtering/design.md

@@ -0,0 +1,61 @@
+## Context
+
+`list_tasks` currently fetches all tasks in scope and returns a flat `TaskSummary` array with no server-side filtering. For large databases, `scope: { all: true }` can return thousands of tasks — far too many for an LLM to reason over. Filtering must happen inside the OmniJS snippet before data crosses the JXA bridge; post-hoc filtering in TypeScript would still pay the full serialization cost.
+
+`TaskSummary` currently omits `dueDate` and `tagIds`. Without these, filtered results are opaque: if the LLM asks "what's due today?" it can't present due dates in its response without issuing a `get_task` call per result.
+
+## Goals / Non-Goals
+
+**Goals:**
+- Filter tasks by `flagged`, `status[]`, `tagId`, and `dueBeforeDate` inside the snippet
+- Enrich `TaskSummary` with `dueDate` and `tagIds`
+- Change default behavior: exclude `complete` and `dropped` tasks when no `status` filter is provided
+- Cap results with a configurable `limit` (default 200)
+
+**Non-Goals:**
+- Multi-tag filtering with AND/OR semantics (future work)
+- Full-text search on task name or note
+- Pagination / cursor-based continuation (hard cap only)
+- Filtering `list_projects` (separate change)
+
+## Decisions
+
+### Decision 1: Filter in snippet, not TypeScript
+
+All filter logic runs inside `evaluateJavascript`. The TypeScript layer passes filter args through and validates the schema. This avoids deserializing thousands of tasks only to discard most of them.
+
+Alternative considered: filter in TS. Rejected because the JXA serialization cost is paid per-task regardless — a 5000-task DB would serialize all 5000 even if only 10 match.
+
+### Decision 2: Enrich TaskSummary with dueDate and tagIds
+
+`TaskSummary` gains two fields:
+- `dueDate: string | null` — ISO datetime
+- `tagIds: string[]`
+
+These are the fields most likely to appear in filtering queries and most useful to display in results. Other detail fields (`note`, `deferDate`, `estimatedMinutes`) remain in `TaskDetail` only.
+
+This is a non-breaking addition to the shape — existing consumers receive new optional fields.
+
+### Decision 3: Default excludes complete and dropped
+
+When `filter.status` is omitted, the snippet filters out `Task.Status.Completed` and `Task.Status.Dropped`. This is a breaking behavior change but the correct default for LLM-driven queries. The previous default (return everything) was only useful for bulk inspection, which can still be achieved with `status: ["available", "blocked", "dueSoon", "next", "overdue", "complete", "dropped"]`.
+
+### Decision 4: Status filter as array, tag filter as single ID
+
+`status` accepts an array of `TaskStatus` values. This lets callers express compound queries ("available OR overdue") in a single call.
+
+`tagId` accepts a single ID — the 80% use case. Multi-tag AND/OR filtering adds significant complexity for uncertain benefit in v1.
+
+### Decision 5: dueBeforeDate is inclusive
+
+`dueBeforeDate` matches tasks where `task.dueDate <= dueBeforeDate`. "Due before end of today" is expressed as the end-of-day ISO timestamp. Null due dates never match.
+
+### Decision 6: limit default 200, passed as snippet arg
+
+The limit is enforced inside the snippet (slice after filtering) so the cap applies before serialization. Default 200. Callers may increase it up to any value — there is no server-side maximum, just the JXA timeout.
+
+## Risks / Trade-offs
+
+- **Breaking default behavior** — consumers that relied on `list_tasks` returning complete tasks will see a behavior change. Risk is low: this is a local MCP server with a single consumer (Claude Desktop), and the new default is strictly more useful.
+- **tagId filter requires flattenedTags lookup** — to check `task.tags`, OmniJS traverses the tag tree. On databases with thousands of tags this is fast in practice but not free.
+- **limit does not paginate** — if a user has 500 overdue tasks and limit is 200, they see the first 200 with no way to retrieve the rest. Acceptable for v1; pagination is future work.

package/openspec/changes/archive/2026-04-09-task-filtering/proposal.md

@@ -0,0 +1,26 @@
+## Why
+
+`list_tasks` currently returns all tasks in scope with no filtering — an LLM asking "what's overdue?" on a large database receives thousands of tasks and must reason over the entire set. Filtering in the snippet before the JXA bridge means the LLM only sees the relevant tasks, making planning queries fast and practical.
+
+## What Changes
+
+- `list_tasks` accepts an optional `filter` object: `flagged`, `status` (array), `tagId`, `dueBeforeDate`
+- `list_tasks` accepts an optional `limit` (default 200)
+- **BREAKING**: Default behavior changes — when no `status` filter is given, complete and dropped tasks are excluded. Pass `status: ["complete"]` explicitly to retrieve completed tasks.
+- `TaskSummary` is enriched with `dueDate` and `tagIds` fields so the LLM can reason about results without fetching full task detail for each match
+
+## Capabilities
+
+### New Capabilities
+- `task-filtering`: Filter parameters and enriched summary for `list_tasks`
+
+### Modified Capabilities
+- `task-management`: `list_tasks` tool signature changes (new filter/limit params, enriched return shape, changed default behavior)
+
+## Impact
+
+- `src/snippets/list_tasks.js` — rewritten to apply filters and return enriched fields
+- `src/schemas/shapes.ts` — `TaskSummary` gains `dueDate` and `tagIds`; new `ListTasksFilter` schema
+- `src/tools/listTasks.ts` — input schema updated with filter and limit
+- `test/unit/tools.listTasks.test.ts` — existing unit tests may need updating for new schema shape
+- `test/integration/listTasks.int.test.ts` — new integration tests for filter combinations

package/openspec/changes/archive/2026-04-09-task-filtering/specs/task-filtering/spec.md

@@ -0,0 +1,63 @@
+## ADDED Requirements
+
+### Requirement: Filter list_tasks results
+
+The system SHALL allow `list_tasks` to accept an optional `filter` object that restricts which tasks are returned. All filter fields are optional and combine as AND conditions. When `filter.status` is omitted, the tool SHALL exclude tasks with status `complete` or `dropped` by default.
+
+Filter fields:
+- `flagged` (boolean): when `true`, return only flagged tasks
+- `status` (array of TaskStatus): return only tasks whose status is in the array; overrides the default exclusion of complete/dropped
+- `tagId` (string): return only tasks that have this tag assigned
+- `dueBeforeDate` (ISO datetime string): return only tasks where `dueDate` is non-null and on or before this date
+
+#### Scenario: Filter by flagged
+- **WHEN** `list_tasks` is called with `{ scope: { all: true }, filter: { flagged: true } }`
+- **THEN** the tool returns only tasks where `flagged` is `true`, excluding complete and dropped tasks
+
+#### Scenario: Filter by status array
+- **WHEN** `list_tasks` is called with `{ scope: { all: true }, filter: { status: ["overdue", "dueSoon"] } }`
+- **THEN** the tool returns only tasks with status `overdue` or `dueSoon`
+
+#### Scenario: Filter by tagId
+- **WHEN** `list_tasks` is called with `{ scope: { projectId: "abc123" }, filter: { tagId: "tag456" } }`
+- **THEN** the tool returns only tasks in that project that have the specified tag assigned
+
+#### Scenario: Filter by dueBeforeDate
+- **WHEN** `list_tasks` is called with `{ scope: { all: true }, filter: { dueBeforeDate: "2026-04-09T23:59:59Z" } }`
+- **THEN** the tool returns only tasks with a non-null dueDate on or before the specified date, excluding complete and dropped tasks
+
+#### Scenario: Default excludes complete and dropped
+- **WHEN** `list_tasks` is called with no filter
+- **THEN** the tool returns tasks with any status except `complete` and `dropped`
+
+#### Scenario: Explicit status filter overrides default exclusion
+- **WHEN** `list_tasks` is called with `{ filter: { status: ["complete"] } }`
+- **THEN** the tool returns completed tasks (the default exclusion does not apply)
+
+#### Scenario: Combined filters act as AND
+- **WHEN** `list_tasks` is called with `{ filter: { flagged: true, tagId: "tag456" } }`
+- **THEN** the tool returns only tasks that are both flagged AND have that tag
+
+### Requirement: Limit list_tasks results
+
+The system SHALL allow `list_tasks` to accept an optional `limit` integer that caps the number of tasks returned. When `limit` is omitted, a default of 200 SHALL apply.
+
+#### Scenario: Default limit of 200
+- **WHEN** `list_tasks` is called without a `limit` and more than 200 tasks match
+- **THEN** the tool returns at most 200 tasks
+
+#### Scenario: Custom limit
+- **WHEN** `list_tasks` is called with `{ limit: 50 }`
+- **THEN** the tool returns at most 50 tasks
+
+### Requirement: Enriched task summary includes dueDate and tagIds
+
+The `TaskSummary` returned by `list_tasks` SHALL include `dueDate` (ISO datetime or null) and `tagIds` (array of tag ID strings) in addition to existing fields.
+
+#### Scenario: Summary includes dueDate
+- **WHEN** `list_tasks` returns a task that has a due date set
+- **THEN** the task summary includes `dueDate` as an ISO datetime string
+
+#### Scenario: Summary includes tagIds
+- **WHEN** `list_tasks` returns a task that has tags assigned
+- **THEN** the task summary includes `tagIds` as an array of tag ID strings

package/openspec/changes/archive/2026-04-09-task-filtering/specs/task-management/spec.md

@@ -0,0 +1,17 @@
+## MODIFIED Requirements
+
+### Requirement: List tasks with scope filter
+
+The system SHALL provide a `list_tasks` tool that returns tasks within a caller-specified scope. The scope SHALL be one of: `{projectId: string}`, `{folderId: string}` (all tasks in projects under that folder, recursively), `{inbox: true}`, or `{all: true}` (the full flattened task list). The tool SHALL accept an optional `filter` object (see task-filtering spec) and an optional `limit` integer (default 200). The tool SHALL return an array of task summaries, each containing `{id, name, status, flagged, containerId, containerType, dueDate, tagIds}`. When no `filter.status` is provided, tasks with status `complete` or `dropped` SHALL be excluded by default.
+
+#### Scenario: List tasks in a specific project
+- **WHEN** `list_tasks` is called with `{projectId: "abc123"}`
+- **THEN** the tool returns actionable tasks (non-complete, non-dropped) directly or transitively contained in that project, each carrying the project id as `containerId` and `"project"` as `containerType`
+
+#### Scenario: List inbox tasks
+- **WHEN** `list_tasks` is called with `{inbox: true}`
+- **THEN** the tool returns actionable inbox tasks with `containerType` set to `"inbox"`
+
+#### Scenario: Invalid scope is rejected at the TS boundary
+- **WHEN** `list_tasks` is called with `{projectId: "abc", inbox: true}` (mutually exclusive scopes)
+- **THEN** the tool returns a validation error before any snippet executes

package/openspec/changes/archive/2026-04-09-task-filtering/tasks.md

@@ -0,0 +1,42 @@
+## 1. Schema changes (src/schemas/)
+
+- [x] 1.1 Add `dueDate: z.string().datetime().nullable()` and `tagIds: z.array(IdSchema)` to `TaskSummary` in `shapes.ts`
+- [x] 1.2 Define `ListTasksFilter` zod schema: `{ flagged: z.literal(true).optional(), status: z.array(TaskStatus).optional(), tagId: IdSchema.optional(), dueBeforeDate: z.string().datetime().optional() }`
+- [x] 1.3 Export `ListTasksFilter` from `src/schemas/index.ts`
+
+## 2. Snippet rewrite (src/snippets/list_tasks.js)
+
+- [x] 2.1 Add `dueDate` and `tagIds` to the `mapTask` helper
+- [x] 2.2 Implement default status exclusion: when `args.filter?.status` is absent, exclude `Task.Status.Completed` and `Task.Status.Dropped`
+- [x] 2.3 Implement `flagged` filter: when `args.filter?.flagged` is `true`, exclude non-flagged tasks
+- [x] 2.4 Implement `status` array filter: when `args.filter?.status` is provided, keep only tasks whose status maps to one of the given strings
+- [x] 2.5 Implement `tagId` filter: when `args.filter?.tagId` is provided, keep only tasks that have a tag whose `id.primaryKey` matches
+- [x] 2.6 Implement `dueBeforeDate` filter: when provided, keep only tasks where `task.dueDate` is non-null and `<= new Date(args.filter.dueBeforeDate)`
+- [x] 2.7 Apply `args.limit` (default 200) as a slice after all filters
+
+## 3. Tool handler update (src/tools/listTasks.ts)
+
+- [x] 3.1 Add `filter: ListTasksFilter.optional()` and `limit: z.number().int().positive().optional()` to `listTasksSchema`
+- [x] 3.2 Pass `filter` and `limit` through to `runSnippet`
+- [x] 3.3 Update tool description to document the filter params and the new default-exclusion behavior
+
+## 4. Unit tests (test/unit/)
+
+- [x] 4.1 Update `tools.listTasks.test.ts`: add `dueDate` and `tagIds` to any TaskSummary fixtures that are now required fields
+- [x] 4.2 Add schema tests for `ListTasksFilter`: valid filter passes; invalid status enum rejected; dueBeforeDate must be ISO datetime
+
+## 5. Integration tests (test/integration/)
+
+- [x] 5.1 `listTasksFiltered.int.test.ts`: create tasks with known properties in a fixture folder; verify `flagged: true` filter returns only flagged tasks
+- [x] 5.2 Verify `status` filter: create a completed task; confirm it is absent by default and present when `status: ["complete"]` is passed
+- [x] 5.3 Verify `tagId` filter: assign a tag to one task; confirm only that task is returned
+- [x] 5.4 Verify `dueBeforeDate` filter: create a task with a due date in the past; confirm it is returned; create one due far in the future; confirm it is not
+- [x] 5.5 Verify `limit`: create more tasks than the limit; confirm result is capped
+- [x] 5.6 Verify enriched summary: returned tasks include non-null `dueDate` and `tagIds` when applicable
+
+## 6. Verification
+
+- [x] 6.1 `npm run typecheck` clean
+- [x] 6.2 `npm test` (unit suite) clean
+- [x] 6.3 Manually run integration suite; verify fixture cleanup
+- [ ] 6.4 Connect to Claude Desktop; exercise filter queries against a real database

package/openspec/changes/archive/2026-04-10-planned-date/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-04-10

package/openspec/changes/archive/2026-04-10-planned-date/design.md

@@ -0,0 +1,27 @@
+## Context
+
+OmniFocus 4 distinguishes three date types on tasks: `deferDate` (hides until), `plannedDate` (Forecast target), and `dueDate` (hard deadline). The MCP server already handles defer and due with the pattern `isoOrNull(task.deferDate)` for reading and `task.deferDate = args.deferDate ? new Date(args.deferDate) : null` for writing. `plannedDate` follows the identical pattern — confirmed writable via OmniJS.
+
+## Goals / Non-Goals
+
+**Goals:**
+- Add `plannedDate` to `create_task`, `edit_task`, `get_task`, and all snippets returning `TaskDetail`
+- Follow the exact same pattern as `deferDate` and `dueDate`
+
+**Non-Goals:**
+- `effectiveDeferDate` / `effectiveDueDate` (computed fields inherited from projects — read-only, not actionable)
+- Planned date on projects (projects don't have `plannedDate` in OmniJS)
+
+## Decisions
+
+### Decision 1: Same pattern as existing dates
+
+`plannedDate` is added as `z.string().datetime().optional()` in `CreateTaskInput`, `z.string().datetime().nullable().optional()` in `EditTaskInput`, and `z.string().datetime().nullable()` in `TaskDetail`. No new abstractions needed.
+
+### Decision 2: All TaskDetail-returning snippets updated
+
+Five snippets return `TaskDetail`: `create_task`, `edit_task`, `get_task`, `complete_task`, `drop_task`. All five get `plannedDate: isoOrNull(task.plannedDate)` added to their return object.
+
+## Risks / Trade-offs
+
+- **Minimal risk** — purely additive, follows established patterns exactly. No behavioral change for existing callers.

package/openspec/changes/archive/2026-04-10-planned-date/proposal.md

@@ -0,0 +1,29 @@
+## Why
+
+OmniFocus 4 has three distinct date concepts — defer, planned, and due — but the MCP server only exposes `deferDate` and `dueDate`. The missing `plannedDate` is the soft "when I intend to work on this" date that shows up in Forecast view without hiding the task or triggering overdue status. This is the right date type for many recurring tasks (e.g., cleaning, reviews) where you want Forecast visibility without hard-deadline pressure.
+
+The OmniJS API already exposes `task.plannedDate` as a fully readable, writable, and clearable property — no API barrier.
+
+## What Changes
+
+- `create_task`: add optional `plannedDate` field
+- `edit_task`: add optional `plannedDate` field (nullable to clear)
+- `get_task` / `TaskDetail`: return `plannedDate` in the detail record
+- All snippets returning `TaskDetail` (`complete_task`, `drop_task`) include `plannedDate`
+
+## Capabilities
+
+### New Capabilities
+
+(none)
+
+### Modified Capabilities
+
+- `task-write`: `create_task` and `edit_task` gain a `plannedDate` parameter
+- `task-management`: `get_task` returns `plannedDate` in `TaskDetail`
+
+## Impact
+
+- `src/schemas/shapes.ts`: `CreateTaskInput`, `EditTaskInput`, `TaskDetail` extended
+- `src/snippets/create_task.js`, `edit_task.js`, `get_task.js`, `complete_task.js`, `drop_task.js`: add `plannedDate` field
+- No breaking changes — all new fields are optional; existing callers unaffected

package/openspec/changes/archive/2026-04-10-planned-date/specs/task-management/spec.md

@@ -0,0 +1,29 @@
+## MODIFIED Requirements
+
+### Requirement: Get task by ID
+
+The system SHALL provide a `get_task` tool that accepts `{id: string}` and returns the full detail record of the named task, including `{id, name, note, status, flagged, deferDate, plannedDate, dueDate, completionDate, estimatedMinutes, containerId, containerType, tagIds, parentTaskId, repetitionRule}`. The `parentTaskId` field SHALL be `null` for top-level tasks and SHALL contain the parent task's `id.primaryKey` for subtasks. The `repetitionRule` field SHALL be `null` when no repetition rule is set, and SHALL be a structured object with `{frequency, interval, daysOfWeek?, method}` when a rule exists. The `plannedDate` field SHALL be `null` when no planned date is set. If no task exists with that ID, the tool SHALL return a structured not-found error.
+
+#### Scenario: Existing task returns full detail
+- **WHEN** `get_task` is called with the ID of an existing task
+- **THEN** the tool returns the task's full detail record including all scalar fields, the list of tag IDs assigned to it, `parentTaskId`, `repetitionRule`, and `plannedDate`
+
+#### Scenario: Subtask includes parentTaskId
+- **WHEN** `get_task` is called with the ID of a subtask
+- **THEN** the returned record includes `parentTaskId` set to the parent task's stable ID
+
+#### Scenario: Task without repetition returns null repetitionRule
+- **WHEN** `get_task` is called for a task with no repetition rule
+- **THEN** the returned TaskDetail includes `repetitionRule: null`
+
+#### Scenario: Task with repetition returns structured repetitionRule
+- **WHEN** `get_task` is called for a task that has a repetition rule
+- **THEN** the returned TaskDetail includes `repetitionRule` with `frequency`, `interval`, `method`, and `daysOfWeek` (if applicable)
+
+#### Scenario: Task with planned date returns plannedDate
+- **WHEN** `get_task` is called for a task that has a planned date set
+- **THEN** the returned TaskDetail includes `plannedDate` as an ISO datetime string
+
+#### Scenario: Missing task returns not-found error
+- **WHEN** `get_task` is called with an ID that does not correspond to any task
+- **THEN** the tool returns a structured error with a not-found code and does not throw an unhandled exception