@scardis/omnifocus-mcp 0.1.0

package/openspec/changes/archive/2026-04-09-move-operations/tasks.md

@@ -0,0 +1,40 @@
+## 1. Schema changes (src/schemas/)
+
+- [x] 1.1 Define `MoveTaskInput` zod schema: `{ id: IdSchema, projectId: IdSchema.optional(), parentTaskId: IdSchema.optional() }` with `.refine()` that exactly one of `projectId` or `parentTaskId` is provided
+- [x] 1.2 Define `MoveProjectInput` zod schema: `{ id: IdSchema, folderId: IdSchema.nullable() }`
+- [x] 1.3 Export `MoveTaskInput` and `MoveProjectInput` from `src/schemas/index.ts`
+
+## 2. Snippets (src/snippets/)
+
+- [x] 2.1 Create `move_task.js`: resolve task by ID (NotFoundError if missing); if `projectId` provided, resolve project (NotFoundError if missing), assign `task.containingProject = project`; if `parentTaskId` provided, resolve parent task (NotFoundError if missing), assign `task.parentTask = parentTask`; return updated `TaskSummary` fields
+- [x] 2.2 Create `move_project.js`: resolve project by ID (NotFoundError if missing); if `folderId` is non-null, resolve folder (NotFoundError if missing), assign `project.parentFolder = folder`; if `folderId` is null, assign `project.parentFolder = null`; return updated `ProjectSummary` fields
+
+## 3. Tool handlers (src/tools/)
+
+- [x] 3.1 Create `moveTask.ts`: schema uses `MoveTaskInput`, handler calls `runSnippet("move_task", input)`, parses result as `TaskSummary`, exports `moveTaskTool`
+- [x] 3.2 Create `moveProject.ts`: schema uses `MoveProjectInput`, handler calls `runSnippet("move_project", input)`, parses result as `ProjectSummary`, exports `moveProjectTool`
+
+## 4. Registration
+
+- [x] 4.1 Add `move_task` and `move_project` to `ALLOWED_SNIPPETS` in `src/runtime/snippetLoader.ts`
+- [x] 4.2 Import and add `moveTaskTool` and `moveProjectTool` to `allTools` in `src/tools/index.ts`
+
+## 5. Unit tests (test/unit/)
+
+- [x] 5.1 Add schema tests for `MoveTaskInput`: valid with projectId only; valid with parentTaskId only; invalid with both; invalid with neither
+- [x] 5.2 Add schema tests for `MoveProjectInput`: valid with folderId string; valid with folderId null; invalid with missing id
+
+## 6. Integration tests (test/integration/)
+
+- [x] 6.1 `moveTask.int.test.ts`: create task in project A; move to project B; verify task appears in project B
+- [x] 6.2 `moveTask.int.test.ts`: create task; make it a subtask of another task via parentTaskId
+- [x] 6.3 `moveTask.int.test.ts`: non-existent task ID returns NotFoundError
+- [x] 6.4 `moveProject.int.test.ts`: create project in folder A; move to folder B; verify project is in folder B
+- [x] 6.5 `moveProject.int.test.ts`: move project to top level (folderId: null)
+- [x] 6.6 `moveProject.int.test.ts`: non-existent project ID returns NotFoundError
+
+## 7. Verification
+
+- [x] 7.1 `npm run typecheck` clean
+- [x] 7.2 `npm test` (unit suite) clean
+- [x] 7.3 Manually run integration suite

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

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

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

@@ -0,0 +1,60 @@
+## Context
+
+Projects in OmniJS have more writable fields than tasks: type (`sequential`, `containsSingletonActions`), review interval, and folder placement. Status transitions use dedicated methods. This design follows the same patterns established in `task-crud`.
+
+OmniJS project write operations:
+- `new Project(name, position)` — creates a project; `position` is a `Folder` or omitted for top-level
+- Property assignment for scalars: `name`, `note`, `flagged`, `deferDate`, `dueDate`, `sequential`, `containsSingletonActions`
+- `project.status = Project.Status.Active / OnHold` — for hold/active transitions
+- `project.markComplete()` — dedicated method for done
+- `project.status = Project.Status.Dropped` — drops the project (`project.drop()` is not available via `evaluateJavascript`)
+- `project.reviewInterval.steps = n` — only `steps` can be mutated in-place; `Project.ReviewInterval` is a CallbackObject in the `evaluateJavascript` context and cannot be constructed with `new`, so the unit cannot be changed and the interval cannot be cleared (OmniJS rejects `null`)
+- Tags: `project.addTag(tag)` / `project.removeTag(tag)` — same pattern as tasks
+- `deleteObject(project)` — permanent deletion including all tasks
+
+## Goals / Non-Goals
+
+**Goals:**
+- Expose create, edit, complete, drop, and delete for projects
+- Support folder placement on create (top-level or inside a folder)
+- Edit any subset of fields in one call including review interval and type
+- Replace-not-merge tag semantics (consistent with task-crud)
+
+**Non-Goals:**
+- Moving a project to a different folder (separate `move-operations` change)
+- Creating tasks inside a new project in the same call (use `create_task` after)
+- Recurrence rules (separate `recurrence` change)
+
+## Decisions
+
+### Decision 1: `type` mapped to OmniJS properties
+
+Project type is not a single OmniJS property — it is encoded across two booleans:
+- `sequential: true` → `"sequential"`
+- `containsSingletonActions: true` → `"singleActions"`
+- both false → `"parallel"`
+
+`create_project` and `edit_project` accept the enum string `"parallel" | "sequential" | "singleActions"` and the snippet maps it to the correct property assignments.
+
+### Decision 2: `reviewInterval` — steps only, in-place mutation
+
+`edit_project` and `create_project` accept `reviewInterval` as `{steps: number, unit: "days" | "weeks" | "months" | "years"}`. Only the `steps` field can actually be applied: `project.reviewInterval.steps = n` mutates the existing interval in place.
+
+**Limitations discovered during implementation:** `Project.ReviewInterval` is a CallbackObject in the `evaluateJavascript` context — `new Project.ReviewInterval(steps, unit)` throws. `Project.ReviewInterval.Unit` is also undefined in this context, so the unit cannot be changed. Setting `project.reviewInterval = null` is rejected by OmniJS ("must be set to a non-null value"). As a result, the `unit` field in `reviewInterval` input is accepted by the schema but silently ignored at runtime.
+
+**Note:** Read output (`get_project`) returns the string form `"1 weeks"` — that is a read-side concern unchanged by this limitation.
+
+### Decision 3: Status transitions via dedicated tools and property assignment
+
+`complete_project` calls `markComplete()`. `drop_project` sets `project.status = Project.Status.Dropped` — `project.drop()` does not exist in the `evaluateJavascript` context. Active/on-hold are set via `project.status = Project.Status.Active / OnHold` inside `edit_project` (these are property assignments, not method calls). This keeps the common "put on hold" operation accessible through `edit_project` without requiring a dedicated tool.
+
+### Decision 4: `delete_project` description warns about task cascade
+
+`deleteObject(project)` removes the project and all its tasks. The tool description explicitly states this. Consistent with `delete_task` and `delete_folder` confirmation pattern.
+
+## Risks / Trade-offs
+
+- **`new Project(name)` without a position** creates a top-level project. Verified in OmniJS.
+- **`new Project(name, folder)` with a Folder object** places the project inside that folder.
+- **Review interval unit enum values** — OmniJS `Project.ReviewInterval.Unit` has `.days`, `.weeks`, `.months`, `.years`. Snippet should map string to the enum member, not pass the string directly.
+- **Changing type from `singleActions`** may silently fail if the project has tasks structured for that mode — low risk for typical usage, not worth guarding against in v1.

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

@@ -0,0 +1,29 @@
+## Why
+
+The bootstrap change delivered read-only project access. Callers can observe projects but cannot create, modify, complete, drop, or delete them — making the server unsuitable for any workflow that involves acting on projects.
+
+## What Changes
+
+- Add `create_project` tool: create a project in a folder or at the top level
+- Add `edit_project` tool: modify any subset of a project's scalar fields, type, tags, and review interval in a single call
+- Add `complete_project` tool: mark a project done
+- Add `drop_project` tool: mark a project dropped
+- Add `delete_project` tool: permanently delete a project and all its tasks (tool description instructs the AI to confirm with the user before invoking)
+
+## Capabilities
+
+### New Capabilities
+
+- `project-write`: Create, edit, complete, drop, and permanently delete OmniFocus projects
+
+### Modified Capabilities
+
+_(none — existing `project-management` read requirements are unchanged)_
+
+## 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-project-crud/specs/project-write/spec.md

@@ -0,0 +1,74 @@
+## ADDED Requirements
+
+### Requirement: Create project
+
+The system SHALL provide a `create_project` tool that creates a new OmniFocus project and returns its full detail record. The tool SHALL accept `{name: string, folderId?: string, note?: string, type?: "parallel" | "sequential" | "singleActions", status?: "active" | "onHold", flagged?: boolean, deferDate?: string, dueDate?: string, reviewInterval?: {steps: number, unit: "days" | "weeks" | "months" | "years"}, tagIds?: string[]}`. If `folderId` is provided the project SHALL be created inside that folder; otherwise it SHALL be created at the top level.
+
+#### Scenario: Create top-level project
+- **WHEN** `create_project` is called with `{name: "My Project"}` and no `folderId`
+- **THEN** the tool creates the project at the top level and returns its full detail record including a stable `id`
+
+#### Scenario: Create project inside a folder
+- **WHEN** `create_project` is called with `{name: "My Project", folderId: "abc123"}`
+- **THEN** the tool creates the project inside the specified folder and returns its full detail record with `folderPath` reflecting the folder
+
+#### Scenario: Create sequential project
+- **WHEN** `create_project` is called with `{name: "My Project", type: "sequential"}`
+- **THEN** the returned project detail includes `type: "sequential"`
+
+#### Scenario: Non-existent folder returns not-found error
+- **WHEN** `create_project` is called with a `folderId` that does not correspond to any folder
+- **THEN** the tool returns a structured not-found error
+
+### Requirement: Edit project
+
+The system SHALL provide an `edit_project` tool that modifies an existing project and returns its updated full detail record. The tool SHALL accept `{id: string}` plus any subset of `{name?: string, note?: string, type?: "parallel" | "sequential" | "singleActions", status?: "active" | "onHold", flagged?: boolean, deferDate?: string | null, dueDate?: string | null, reviewInterval?: {steps: number, unit: "days" | "weeks" | "months" | "years"}, tagIds?: string[]}`. Fields omitted from the call SHALL be left unchanged. When `tagIds` is provided it SHALL replace the project's entire tag set. Passing `null` for a date SHALL clear the field. When `reviewInterval` is provided, only the `steps` value is updated; the `unit` field is accepted by the schema but cannot be changed at runtime due to OmniJS API constraints in the `evaluateJavascript` context.
+
+#### Scenario: Put project on hold
+- **WHEN** `edit_project` is called with `{id: "abc123", status: "onHold"}`
+- **THEN** the project's status becomes `"onHold"` and all other fields are unchanged
+
+#### Scenario: Set review interval
+- **WHEN** `edit_project` is called with `{id: "abc123", reviewInterval: {steps: 2, unit: "weeks"}}`
+- **THEN** the project's review interval is updated and the returned detail reflects the change
+
+
+#### Scenario: Non-existent project returns not-found error
+- **WHEN** `edit_project` is called with an ID that does not correspond to any project
+- **THEN** the tool returns a structured not-found error
+
+### Requirement: Complete project
+
+The system SHALL provide a `complete_project` tool that marks an existing project done using OmniJS `markComplete()` and returns the project's updated full detail record.
+
+#### Scenario: Complete an existing project
+- **WHEN** `complete_project` is called with the ID of an active project
+- **THEN** the project's status becomes `"done"` and the tool returns the updated detail record
+
+#### Scenario: Non-existent project returns not-found error
+- **WHEN** `complete_project` is called with an ID that does not correspond to any project
+- **THEN** the tool returns a structured not-found error
+
+### Requirement: Drop project
+
+The system SHALL provide a `drop_project` tool that marks an existing project dropped using OmniJS `drop()` and returns the project's updated full detail record.
+
+#### Scenario: Drop an existing project
+- **WHEN** `drop_project` is called with the ID of an active project
+- **THEN** the project's status becomes `"dropped"` and the tool returns the updated detail record
+
+#### Scenario: Non-existent project returns not-found error
+- **WHEN** `drop_project` is called with an ID that does not correspond to any project
+- **THEN** the tool returns a structured not-found error
+
+### Requirement: Delete project
+
+The system SHALL provide a `delete_project` tool that permanently deletes a project and all its tasks 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 removes all tasks within the project.
+
+#### Scenario: Delete an existing project
+- **WHEN** `delete_project` is called with the ID of an existing project
+- **THEN** the project and all its tasks are permanently removed from OmniFocus and the tool returns a confirmation envelope
+
+#### Scenario: Non-existent project returns not-found error
+- **WHEN** `delete_project` is called with an ID that does not correspond to any project
+- **THEN** the tool returns a structured not-found error

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

@@ -0,0 +1,48 @@
+## 1. Snippets (src/snippets/)
+
+- [x] 1.1 `create_project.js`: accept `{name, folderId?, note?, type?, status?, flagged?, deferDate?, dueDate?, reviewInterval?, tagIds?}`; resolve folder by ID if provided; map `type` string to `sequential`/`containsSingletonActions` booleans; set `status` to `Project.Status.OnHold` if `"onHold"`; construct `new Project.ReviewInterval(steps, unit)` if `reviewInterval` provided; resolve and assign tags by ID; return full project detail envelope
+- [x] 1.2 `edit_project.js`: accept `{id, name?, note?, type?, status?, flagged?, deferDate?, dueDate?, reviewInterval?, tagIds?}`; resolve project by ID; apply only provided fields; map `type` and `status` to OmniJS equivalents; handle `null` for date/reviewInterval to clear; replace tag set when `tagIds` provided; return updated full detail envelope
+- [x] 1.3 `complete_project.js`: accept `{id}`; resolve project by ID; call `project.markComplete()`; return updated full detail envelope
+- [x] 1.4 `drop_project.js`: accept `{id}`; resolve project by ID; use `project.status = Project.Status.Dropped` (project.drop() is not available via evaluateJavascript); return updated full detail envelope
+- [x] 1.5 `delete_project.js`: accept `{id}`; resolve project by ID; call `deleteObject(project)`; return `{ok: true, data: {id}}`
+
+## 2. Snippet allowlist
+
+- [x] 2.1 Add `create_project`, `edit_project`, `complete_project`, `drop_project`, `delete_project` to `ALLOWED_SNIPPETS` in `src/runtime/snippetLoader.ts`
+
+## 3. Schemas (src/schemas/shapes.ts)
+
+- [x] 3.1 Define `ReviewIntervalInput` zod schema: `{steps: z.number().int().positive(), unit: z.enum(["days","weeks","months","years"])}`
+- [x] 3.2 Define `CreateProjectInput` zod schema with all optional fields including `reviewInterval: ReviewIntervalInput.optional()`
+- [x] 3.3 Define `EditProjectInput` zod schema — `id` required; date fields accept `string | null`; `reviewInterval` accepts `ReviewIntervalInput` (null not supported — OmniJS rejects null for this property)
+
+## 4. Tool handlers (src/tools/)
+
+- [x] 4.1 `createProject.ts`: validate input with `CreateProjectInput`; invoke `runSnippet("create_project", args)`; validate result against `ProjectDetail`; return
+- [x] 4.2 `editProject.ts`: validate input with `EditProjectInput`; invoke `runSnippet("edit_project", args)`; validate result against `ProjectDetail`; return
+- [x] 4.3 `completeProject.ts`: input `{id: IdSchema}`; invoke `runSnippet("complete_project", {id})`; validate result against `ProjectDetail`; return
+- [x] 4.4 `dropProject.ts`: input `{id: IdSchema}`; invoke `runSnippet("drop_project", {id})`; validate result against `ProjectDetail`; return
+- [x] 4.5 `deleteProject.ts`: input `{id: IdSchema}`; tool description MUST state the AI should confirm with the user before invoking and note that all tasks in the project are permanently deleted; invoke `runSnippet("delete_project", {id})`; return confirmation
+
+## 5. Server registration
+
+- [x] 5.1 Export all five new tool definitions from `src/tools/index.ts`
+
+## 6. Unit tests (test/unit/)
+
+- [x] 6.1 `schemas.createProject.test.ts`: valid inputs pass; invalid `type` enum rejected; invalid `reviewInterval.unit` rejected; null dates accepted in edit schema
+
+## 7. Integration tests (test/integration/)
+
+- [x] 7.1 `createProject.int.test.ts`: create top-level project; create project in folder; verify `folderPath` and `type`
+- [x] 7.2 `editProject.int.test.ts`: edit name; set on-hold; set review interval steps; (clear review interval not supported — OmniJS rejects null)
+- [x] 7.3 `completeProject.int.test.ts`: complete a project, verify status = `"done"`
+- [x] 7.4 `dropProject.int.test.ts`: drop a project, verify status = `"dropped"`
+- [x] 7.5 `deleteProject.int.test.ts`: delete a project, verify subsequent `get_project` returns not-found
+
+## 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 five tools against a real database

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

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

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

@@ -0,0 +1,52 @@
+## Context
+
+`list_projects` currently fetches all projects and returns a flat `ProjectSummary` array with no filtering. This mirrors the pre-filtering state of `list_tasks`. The task-filtering change established the pattern: filter inside the OmniJS snippet before data crosses the JXA bridge, enrich the summary shape with fields needed for filtering and display, change the default to exclude terminal statuses.
+
+`ProjectSummary` currently omits `flagged` and the parent folder ID (it has `folderPath` string but not `folderId`). Without `folderId`, the LLM cannot cross-reference a listed project with a known folder ID, and cannot filter by folder ID from returned results.
+
+## Goals / Non-Goals
+
+**Goals:**
+- Filter projects by `status[]`, `folderId` (recursive subtree), and `flagged` inside the snippet
+- Enrich `ProjectSummary` with `flagged` and `folderId`
+- Change default behavior: exclude `done` and `dropped` projects when no `status` filter is provided
+- Cap results with a configurable `limit` (default 100)
+
+**Non-Goals:**
+- Filtering by tag, due date, or review date (can be added later)
+- Filtering `list_folders` or `list_tags` (separate changes if needed)
+- Pagination / cursor-based continuation
+
+## Decisions
+
+### Decision 1: Same pattern as task-filtering — filter in snippet
+
+All filter logic runs inside `evaluateJavascript`. The TypeScript layer validates the schema and passes filter args through. Consistent with task-filtering; avoids any future performance concerns if project counts grow.
+
+### Decision 2: Enrich ProjectSummary with flagged and folderId
+
+`ProjectSummary` gains:
+- `flagged: boolean` — needed to support the `flagged` filter and display flagged state in results
+- `folderId: string | null` — the direct parent folder's `id.primaryKey`, or `null` for top-level projects
+
+`folderPath` is kept as-is (useful for display). `folderId` is added alongside it as the machine-readable reference. No other detail fields are promoted to the summary.
+
+### Decision 3: Default excludes done and dropped
+
+When `filter.status` is omitted, the snippet excludes `Project.Status.Done` and `Project.Status.Dropped`. This mirrors the task-filtering default and is the correct behavior for LLM planning queries. Done/dropped projects can be retrieved explicitly with `status: ["done"]` or `status: ["dropped"]`.
+
+### Decision 4: folderId filter is recursive
+
+When `filter.folderId` is provided, the snippet returns projects whose parent folder chain includes the specified folder ID — i.e., direct children and all nested descendants. This is consistent with how `list_tasks` treats `scope.folderId`.
+
+Implementation: check `p.flattenedProjects` on the resolved folder rather than walking `flattenedProjects` globally and checking ancestry. More efficient and correct.
+
+### Decision 5: limit default 100
+
+Projects are fewer than tasks; 100 is a sensible default. Callers may increase it.
+
+## Risks / Trade-offs
+
+- **Breaking default behavior** — same risk as task-filtering. Acceptable: single consumer, new default is strictly more useful.
+- **folderId recursive filter uses folder.flattenedProjects** — this is the cleanest OmniJS approach. If the folder ID is invalid, return an empty array (not an error) since this is a filter, not a scope requirement. Actually: throw NotFoundError to be consistent with list_tasks scope behavior.
+- **flagged on ProjectSummary is a new required field** — any existing unit test fixtures for ProjectSummary will need updating (same situation as TaskSummary in task-filtering).

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

@@ -0,0 +1,26 @@
+## Why
+
+`list_projects` currently returns every project in the database with no filtering. Users with years of OmniFocus history may have hundreds of completed (`done`) and dropped projects, making it impractical for an LLM to identify what's actually active. Applying the same filter-in-snippet pattern established by task-filtering gives the LLM a useful, scoped view of the project list.
+
+## What Changes
+
+- `list_projects` accepts an optional `filter` object: `status` (array), `folderId` (recursive subtree), `flagged`
+- `list_projects` accepts an optional `limit` (default 100)
+- **BREAKING**: Default behavior changes — when no `status` filter is given, `done` and `dropped` projects are excluded. Pass `status: ["done"]` explicitly to retrieve completed projects.
+- `ProjectSummary` is enriched with `flagged` (boolean) and `folderId` (string | null — the direct parent folder's ID) so the LLM can reason about results without fetching full project detail
+
+## Capabilities
+
+### New Capabilities
+- `project-filtering`: Filter parameters and enriched summary for `list_projects`
+
+### Modified Capabilities
+- `project-management`: `list_projects` tool signature changes (new filter/limit params, enriched return shape, changed default behavior)
+
+## Impact
+
+- `src/snippets/list_projects.js` — rewritten to apply filters and return enriched fields
+- `src/schemas/shapes.ts` — `ProjectSummary` gains `flagged` and `folderId`; new `ListProjectsFilter` schema
+- `src/tools/listProjects.ts` — input schema updated with filter and limit
+- `test/unit/` — schema tests for new filter type
+- `test/integration/listProjectsFiltered.int.test.ts` — new integration tests for filter combinations

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

@@ -0,0 +1,66 @@
+## ADDED Requirements
+
+### Requirement: Filter list_projects results
+
+The system SHALL allow `list_projects` to accept an optional `filter` object that restricts which projects are returned. All filter fields are optional and combine as AND conditions. When `filter.status` is omitted, the tool SHALL exclude projects with status `done` or `dropped` by default.
+
+Filter fields:
+- `status` (array of ProjectStatus): return only projects whose status is in the array; overrides the default exclusion of done/dropped
+- `folderId` (string): return only projects within the specified folder or any of its descendant folders; throws not-found if the folder ID does not exist
+- `flagged` (boolean): when `true`, return only flagged projects
+
+#### Scenario: Default excludes done and dropped projects
+- **WHEN** `list_projects` is called with no filter
+- **THEN** the tool returns only projects with status `active` or `onHold`
+
+#### Scenario: Filter by status array
+- **WHEN** `list_projects` is called with `{ filter: { status: ["active"] } }`
+- **THEN** the tool returns only active projects
+
+#### Scenario: Explicit status filter retrieves done projects
+- **WHEN** `list_projects` is called with `{ filter: { status: ["done"] } }`
+- **THEN** the tool returns completed projects (the default exclusion does not apply)
+
+#### Scenario: Filter by folderId returns projects in subtree
+- **WHEN** `list_projects` is called with `{ filter: { folderId: "abc123" } }`
+- **THEN** the tool returns only projects whose parent folder chain includes the specified folder
+
+#### Scenario: Non-existent folderId returns not-found error
+- **WHEN** `list_projects` is called with a `folderId` that does not correspond to any folder
+- **THEN** the tool returns a structured not-found error
+
+#### Scenario: Filter by flagged
+- **WHEN** `list_projects` is called with `{ filter: { flagged: true } }`
+- **THEN** the tool returns only flagged projects, excluding done and dropped projects
+
+#### Scenario: Combined filters act as AND
+- **WHEN** `list_projects` is called with `{ filter: { status: ["active"], flagged: true } }`
+- **THEN** the tool returns only projects that are both active AND flagged
+
+### Requirement: Limit list_projects results
+
+The system SHALL allow `list_projects` to accept an optional `limit` integer that caps the number of projects returned. When `limit` is omitted, a default of 100 SHALL apply.
+
+#### Scenario: Default limit of 100
+- **WHEN** `list_projects` is called without a `limit` and more than 100 projects match
+- **THEN** the tool returns at most 100 projects
+
+#### Scenario: Custom limit
+- **WHEN** `list_projects` is called with `{ limit: 20 }`
+- **THEN** the tool returns at most 20 projects
+
+### Requirement: Enriched project summary includes flagged and folderId
+
+The `ProjectSummary` returned by `list_projects` SHALL include `flagged` (boolean) and `folderId` (string or null) in addition to existing fields. `folderId` SHALL be the direct parent folder's `id.primaryKey`, or `null` for top-level projects.
+
+#### Scenario: Summary includes flagged
+- **WHEN** `list_projects` returns a flagged project
+- **THEN** the project summary includes `flagged: true`
+
+#### Scenario: Summary includes folderId for nested project
+- **WHEN** `list_projects` returns a project inside a folder
+- **THEN** the project summary includes `folderId` set to the parent folder's ID
+
+#### Scenario: Summary includes folderId null for top-level project
+- **WHEN** `list_projects` returns a top-level project with no containing folder
+- **THEN** the project summary includes `folderId: null`

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

@@ -0,0 +1,13 @@
+## MODIFIED Requirements
+
+### Requirement: List projects
+
+The system SHALL provide a `list_projects` tool that returns projects in the OmniFocus database as an array of summaries, each containing `{id, name, folderPath, folderId, status, type, flagged}`. The `status` field SHALL be one of `"active" | "onHold" | "done" | "dropped"`. The `type` field SHALL be one of `"parallel" | "sequential" | "singleActions"`. The `folderPath` field SHALL use the canonical ` ▸ ` separator and SHALL be an empty string for top-level projects. The `folderId` field SHALL be the direct parent folder's ID or `null` for top-level projects. The tool SHALL accept an optional `filter` object (see project-filtering spec) and an optional `limit` integer (default 100). When no `filter.status` is provided, projects with status `done` or `dropped` SHALL be excluded by default.
+
+#### Scenario: Active and on-hold projects returned by default
+- **WHEN** `list_projects` is called with no arguments
+- **THEN** the tool returns only projects with status `active` or `onHold`, each with id, name, folderPath, folderId, status, type, and flagged populated
+
+#### Scenario: Single Actions list is reported with correct type
+- **WHEN** the database contains a Single Actions list project
+- **THEN** that project appears in the result with `type: "singleActions"`, never as `"parallel"` or `"sequential"`

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

@@ -0,0 +1,41 @@
+## 1. Schema changes (src/schemas/)
+
+- [x] 1.1 Add `flagged: z.boolean()` and `folderId: IdSchema.nullable()` to `ProjectSummary` in `shapes.ts`
+- [x] 1.2 Define `ListProjectsFilter` zod schema: `{ status: z.array(ProjectStatus).optional(), folderId: IdSchema.optional(), flagged: z.literal(true).optional() }`
+- [x] 1.3 Export `ListProjectsFilter` from `src/schemas/index.ts`
+
+## 2. Snippet rewrite (src/snippets/list_projects.js)
+
+- [x] 2.1 Add `flagged` and `folderId` (parent folder's `id.primaryKey` or `null`) to the project mapping helper
+- [x] 2.2 Implement default status exclusion: when `args.filter?.status` is absent, exclude `Project.Status.Done` and `Project.Status.Dropped`
+- [x] 2.3 Implement `status` array filter: when `args.filter?.status` is provided, keep only projects whose status maps to one of the given strings
+- [x] 2.4 Implement `folderId` filter: resolve the folder by ID (throw `NotFoundError` if not found), then use `folder.flattenedProjects` to get the matching set before applying other filters
+- [x] 2.5 Implement `flagged` filter: when `args.filter?.flagged` is `true`, keep only flagged projects
+- [x] 2.6 Apply `args.limit` (default 100) as a slice after all filters
+
+## 3. Tool handler update (src/tools/listProjects.ts)
+
+- [x] 3.1 Add `filter: ListProjectsFilter.optional()` and `limit: z.number().int().positive().optional()` to `listProjectsSchema`
+- [x] 3.2 Pass `filter` and `limit` through to `runSnippet`
+- [x] 3.3 Update tool description to document filter params and new default-exclusion behavior
+
+## 4. Unit tests (test/unit/)
+
+- [x] 4.1 Search for any `ProjectSummary` fixtures in unit tests and add `flagged` and `folderId` fields
+- [x] 4.2 Add schema tests for `ListProjectsFilter`: valid filter passes; invalid status enum rejected; `flagged: false` rejected (must be literal `true` or absent)
+
+## 5. Integration tests (test/integration/)
+
+- [x] 5.1 `listProjectsFiltered.int.test.ts`: create projects with known properties; verify default excludes done/dropped projects
+- [x] 5.2 Verify `status` filter: create a completed project; confirm absent by default and present when `status: ["done"]` is passed
+- [x] 5.3 Verify `folderId` filter: confirm only projects in that folder's subtree are returned
+- [x] 5.4 Verify `flagged` filter: create flagged and unflagged projects; confirm only flagged returned
+- [x] 5.5 Verify `limit`: confirm result is capped
+- [x] 5.6 Verify enriched summary: returned projects include correct `flagged` and `folderId` fields
+
+## 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-09-tag-crud/.openspec.yaml

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

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

@@ -0,0 +1,45 @@
+## Context
+
+Tags in OmniJS form a tree (parent/child nesting) and have a `status` property (`active`, `onHold`, `dropped`). Write operations are straightforward. Deleting a tag with child tags removes the entire subtree; tasks that held the tag have it automatically removed by OmniFocus.
+
+OmniJS tag write operations:
+- `new Tag(name)` — creates a top-level tag
+- `new Tag(name, parentTag)` — creates a child tag nested under `parentTag`
+- `tag.name = "..."` — rename
+- `tag.status = Tag.Status.Active / OnHold / Dropped` — status transitions
+- `deleteObject(tag)` — removes the tag; child tags and task associations are cleaned up by OmniFocus automatically (unlike folders/projects, no manual cascade needed)
+
+## Goals / Non-Goals
+
+**Goals:**
+- Create top-level and child tags
+- Rename tags and change their status
+- Delete tags (OmniFocus handles the cascade automatically)
+
+**Non-Goals:**
+- Moving a tag to a different parent (separate `move-operations` change)
+
+## Decisions
+
+### Decision 1: `deleteObject(tag)` is safe without manual cascade
+
+Unlike folders, `deleteObject(tag)` in OmniJS removes the tag, its child tags, and all task/project tag associations automatically. No recursive snippet logic is needed.
+
+**Verification needed during implementation:** confirm child tags are removed and task associations are cleaned. If this proves incorrect, apply the folder recursive pattern.
+
+### Decision 2: `edit_tag` exposes both `name` and `status`
+
+Tags have a meaningful `status` (`active`, `onHold`, `dropped`) that users set intentionally. Unlike folder status (which is derived), tag status is directly writable and useful — e.g., putting a context tag on hold while travelling. Both `name` and `status` are optional fields in `edit_tag`.
+
+### Decision 3: `create_tag` placement via optional `parentTagId`
+
+- `parentTagId` omitted → top-level tag
+- `parentTagId` provided → child tag nested under that tag
+
+Same pattern as `create_folder` with `parentFolderId`.
+
+## Risks / Trade-offs
+
+- **Deleting a tag with many children** — automatic cascade by OmniFocus; no performance concern beyond normal `deleteObject` overhead.
+- **`tag.status` enum values** — OmniJS uses `Tag.Status.Active`, `Tag.Status.OnHold`, `Tag.Status.Dropped`. Snippet must map input strings to the correct enum members.
+- **Renaming a tag used in many tasks** — OmniFocus updates all associations automatically (tags are objects with stable IDs, not strings).

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

@@ -0,0 +1,28 @@
+## Why
+
+The bootstrap change delivered read-only tag access. Callers can read the tag hierarchy but cannot create new tags, rename existing ones, or delete them — blocking workflows that involve tagging tasks with tags that don't yet exist or maintaining the tag taxonomy.
+
+## What Changes
+
+- Add `create_tag` tool: create a top-level tag or a child tag nested under an existing tag
+- Add `edit_tag` tool: rename a tag
+- Add `delete_tag` tool: permanently delete a tag; tasks that held the tag have it removed (tool description instructs the AI to confirm with the user before invoking)
+
+## Capabilities
+
+### New Capabilities
+
+- `tag-write`: Create, rename, and permanently delete OmniFocus tags
+
+### Modified Capabilities
+
+_(none — existing `tag-management` read requirements are unchanged)_
+
+## Impact
+
+- 3 new MCP tools registered in `src/server.ts`
+- 3 new tool handler files in `src/tools/`
+- 3 new OmniJS snippets in `src/snippets/`
+- `ALLOWED_SNIPPETS` allowlist in `src/runtime/snippetLoader.ts` must be extended
+- Deleting a tag with child tags also removes all descendants; tool description should note this
+- Integration tests will mutate real OmniFocus data (scoped to fixture folder per existing pattern)

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

@@ -0,0 +1,49 @@
+## ADDED Requirements
+
+### Requirement: Create tag
+
+The system SHALL provide a `create_tag` tool that creates a new OmniFocus tag and returns its full detail record. The tool SHALL accept `{name: string, parentTagId?: string}`. If `parentTagId` is provided the tag SHALL be created nested under that tag; otherwise it SHALL be created at the top level.
+
+#### Scenario: Create top-level tag
+- **WHEN** `create_tag` is called with `{name: "Waiting"}` and no `parentTagId`
+- **THEN** the tool creates the tag at the top level and returns its full detail record including a stable `id`
+
+#### Scenario: Create child tag
+- **WHEN** `create_tag` is called with `{name: "Email", parentTagId: "abc123"}`
+- **THEN** the tool creates the tag nested under the specified parent tag and returns its full detail record with `path` and `parentId` set correctly
+
+#### Scenario: Non-existent parent tag returns not-found error
+- **WHEN** `create_tag` is called with a `parentTagId` that does not correspond to any tag
+- **THEN** the tool returns a structured not-found error
+
+### Requirement: Edit tag
+
+The system SHALL provide an `edit_tag` tool that modifies an existing tag and returns its updated full detail record. The tool SHALL accept `{id: string}` plus any subset of `{name?: string, status?: "active" | "onHold" | "dropped"}`. Fields omitted SHALL be left unchanged.
+
+#### Scenario: Rename a tag
+- **WHEN** `edit_tag` is called with `{id: "abc123", name: "Delegated"}`
+- **THEN** the tag's name is updated and the tool returns the updated detail record
+
+#### Scenario: Put tag on hold
+- **WHEN** `edit_tag` is called with `{id: "abc123", status: "onHold"}`
+- **THEN** the tag's status becomes `"onHold"` and the tool returns the updated detail record
+
+#### Scenario: Non-existent tag returns not-found error
+- **WHEN** `edit_tag` is called with an ID that does not correspond to any tag
+- **THEN** the tool returns a structured not-found error
+
+### Requirement: Delete tag
+
+The system SHALL provide a `delete_tag` tool that permanently deletes a tag and all its child tags using OmniJS `deleteObject()`. Tasks and projects that held the tag have it removed automatically by OmniFocus. The tool description SHALL instruct the AI to confirm with the user before invoking, noting that child tags are also deleted.
+
+#### Scenario: Delete a tag
+- **WHEN** `delete_tag` is called with the ID of an existing tag
+- **THEN** the tag is permanently removed from OmniFocus, all tasks that held it have it removed, and the tool returns a confirmation envelope
+
+#### Scenario: Delete tag with children removes entire subtree
+- **WHEN** `delete_tag` is called with the ID of a tag that has child tags
+- **THEN** the tag and all its descendant tags are deleted
+
+#### Scenario: Non-existent tag returns not-found error
+- **WHEN** `delete_tag` is called with an ID that does not correspond to any tag
+- **THEN** the tool returns a structured not-found error