@scardis/omnifocus-mcp 0.1.0 → 0.1.2

package/openspec/changes/archive/2026-04-09-bootstrap-omnifocus-mcp/specs/execution-runtime/spec.md

@@ -1,69 +0,0 @@
-## ADDED Requirements
-
-### Requirement: OmniJS execution via JXA bridge
-
-The system SHALL execute every OmniFocus domain operation inside OmniFocus's OmniJS runtime by invoking `Application('OmniFocus').evaluateJavascript(snippet)` from a JXA host process spawned via `osascript -l JavaScript`. The JXA host SHALL NOT invoke any OmniFocus scripting-dictionary method other than `evaluateJavascript` for domain operations.
-
-#### Scenario: Tool invocation routes through the bridge
-- **WHEN** a tool handler invokes the runtime with a snippet and args
-- **THEN** the runtime spawns `osascript -l JavaScript`, passes a JXA wrapper that calls `Application('OmniFocus').evaluateJavascript` with the prepared snippet, and awaits stdout
-
-#### Scenario: Scripting-dictionary domain methods are forbidden
-- **WHEN** a contributor adds a tool handler that calls e.g. `Application('OmniFocus').defaultDocument.projects` directly
-- **THEN** a unit test (or review) flags the call as a runtime-contract violation and the change is rejected
-
-### Requirement: Snippet argument injection via JSON literal
-
-The system SHALL construct executable scripts by replacing exactly one `__ARGS__` placeholder in a static `.js` snippet template with the result of `JSON.stringify(args)`. No other interpolation of user-supplied data into script source is permitted anywhere in the codebase.
-
-#### Scenario: Apostrophes and quotes survive injection
-- **WHEN** a tool is invoked with `args = {name: "Finn's \"birthday\""}`
-- **THEN** the executed snippet receives `args.name === "Finn's \"birthday\""` and no syntax error occurs
-
-#### Scenario: Unicode and newlines survive injection
-- **WHEN** a tool is invoked with `args = {note: "line1\nline2 — emoji 🎯"}`
-- **THEN** the executed snippet receives the note verbatim including the newline and unicode code points
-
-#### Scenario: Snippets are standalone and paste-ready
-- **WHEN** a developer opens any file under `src/snippets/`
-- **THEN** the file is a valid JavaScript program that can be pasted into OmniFocus's Automation Console after replacing `__ARGS__` with a hand-written object literal, with no additional preprocessing required
-
-### Requirement: One-line JSON result protocol
-
-The system SHALL represent every bridge invocation's result as exactly one line of JSON on the JXA host's stdout, matching the envelope `{ok: true, data: <value>} | {ok: false, error: {name: string, message: string, stack?: string}}`. The TypeScript runtime SHALL read stdout, extract the first JSON-parseable line, and return the parsed envelope to the caller. A result envelope with `ok: false` SHALL be thrown as a structured error with the error details preserved.
-
-#### Scenario: Successful operation returns data envelope
-- **WHEN** a snippet completes without throwing and its final expression is `JSON.stringify({ok: true, data: {id: "abc"}})`
-- **THEN** the TS runtime receives `{ok: true, data: {id: "abc"}}` and returns `{id: "abc"}` to the tool handler
-
-#### Scenario: Snippet exception produces error envelope
-- **WHEN** a snippet throws an `Error` with message "not found"
-- **THEN** the JXA shim catches the exception, prints `{ok: false, error: {name: "Error", message: "not found", ...}}` as one line on stdout, and the TS runtime throws a structured error carrying the name, message, and stack
-
-#### Scenario: Extraneous stdout chatter does not corrupt results
-- **WHEN** any process in the pipeline writes incidental non-JSON output to stdout before the result line
-- **THEN** the TS runtime still parses the result envelope correctly by selecting the first complete JSON-parseable line
-
-### Requirement: Snippet loader
-
-The system SHALL load snippet templates from `src/snippets/<name>.js` relative to the compiled server's known snippet root, caching the file contents in memory after the first read. The loader SHALL reject snippets that do not contain exactly one `__ARGS__` token.
-
-#### Scenario: Snippet is loaded and cached
-- **WHEN** a tool handler invokes the runtime with snippet name `"list_projects"` twice in the same process
-- **THEN** the file `list_projects.js` is read from disk exactly once and the cached content is used for the second invocation
-
-#### Scenario: Snippet with zero placeholders is rejected
-- **WHEN** a snippet file contains no `__ARGS__` token
-- **THEN** the loader throws a contract violation at load time, not at runtime
-
-#### Scenario: Snippet with multiple placeholders is rejected
-- **WHEN** a snippet file contains two or more `__ARGS__` tokens
-- **THEN** the loader throws a contract violation at load time
-
-### Requirement: Script timeout
-
-The system SHALL enforce a configurable per-invocation timeout on `osascript` execution, defaulting to 30 seconds, and SHALL terminate the child process and throw a timeout error when exceeded.
-
-#### Scenario: Long-running snippet is terminated
-- **WHEN** a snippet runs longer than the configured timeout
-- **THEN** the runtime sends SIGTERM to the `osascript` process and throws a timeout error identifying the snippet name and elapsed time

package/openspec/changes/archive/2026-04-09-bootstrap-omnifocus-mcp/specs/folder-management/spec.md

@@ -1,25 +0,0 @@
-## ADDED Requirements
-
-### Requirement: List folders
-
-The system SHALL provide a `list_folders` tool that returns every folder in the OmniFocus database as an array of summaries, each containing at minimum `{id, name, path, parentId, status}`. The `path` field SHALL use the canonical ` ▸ ` separator and SHALL equal the folder's name for top-level folders. The `parentId` field SHALL be `null` for top-level folders. The `status` field SHALL be one of `"active" | "dropped"`.
-
-#### Scenario: All folders are returned with full paths
-- **WHEN** `list_folders` is called with no arguments
-- **THEN** the tool returns every folder in the database including nested folders, each with its full ancestor path
-
-#### Scenario: Top-level folders have null parent
-- **WHEN** a folder exists at the root of the folder hierarchy
-- **THEN** its summary carries `parentId: null` and `path` equal to its name
-
-### Requirement: Get folder by ID
-
-The system SHALL provide a `get_folder` tool that accepts `{id: string}` and returns the full detail record of the named folder, including `{id, name, path, parentId, status, childFolderIds, projectIds}`. If no folder exists with that ID, the tool SHALL return a structured not-found error.
-
-#### Scenario: Existing folder returns full detail with children
-- **WHEN** `get_folder` is called with the ID of an existing folder
-- **THEN** the tool returns the folder's full detail including the IDs of its immediate child folders and immediate child projects
-
-#### Scenario: Missing folder returns not-found error
-- **WHEN** `get_folder` is called with an ID that does not correspond to any folder
-- **THEN** the tool returns a structured error with a not-found code

package/openspec/changes/archive/2026-04-09-bootstrap-omnifocus-mcp/specs/forecast/spec.md

@@ -1,9 +0,0 @@
-## ADDED Requirements
-
-### Requirement: Capability declared
-
-The `forecast` capability SHALL cover OmniFocus Forecast data, including forecast days, tasks due or deferred on a given day, the configured forecast tag, and forecast badge counts. Requirements for individual tools SHALL be added by the `forecast-and-inspection` change.
-
-#### Scenario: Capability is named and scoped
-- **WHEN** a future change proposes adding forecast tools
-- **THEN** it lands requirements under this capability rather than inventing a new capability name

package/openspec/changes/archive/2026-04-09-bootstrap-omnifocus-mcp/specs/identity-resolution/spec.md

@@ -1,45 +0,0 @@
-## ADDED Requirements
-
-### Requirement: Canonical ID addressing
-
-The system SHALL use `id.primaryKey` as the canonical identifier for every addressable OmniFocus entity (Task, Project, Folder, Tag, Perspective). Every read tool SHALL return an `id` field carrying this value. Every write tool (in this and future changes) SHALL accept an `id` parameter as its primary addressing mode.
-
-#### Scenario: Read tools return primary key
-- **WHEN** a caller invokes `list_projects`
-- **THEN** every returned element has an `id` field equal to the OmniJS expression `project.id.primaryKey` for that project
-
-#### Scenario: IDs are stable within a session
-- **WHEN** a caller reads a project's ID via `list_projects`, then reads the same project again via `get_project` using that ID
-- **THEN** the second read succeeds and returns the same project, without re-resolving by name
-
-### Requirement: Name and path resolution with ambiguity reporting
-
-The system SHALL provide a `resolve_name` tool that accepts `{type, query, scope?}` and returns a list of candidate entities `[{id, name, path, type, ...}]`. When more than one entity matches the query, the tool SHALL return all matches and SHALL NOT silently pick a winner. The caller is responsible for disambiguating.
-
-#### Scenario: Unique match returns single candidate
-- **WHEN** `resolve_name` is called with `{type: "project", query: "Q4 Planning"}` and exactly one project has that name
-- **THEN** the tool returns a list with one element containing the project's id, name, and full folder path
-
-#### Scenario: Ambiguous match returns all candidates
-- **WHEN** `resolve_name` is called with `{type: "project", query: "Inbox Cleanup"}` and two projects have that name under different folders
-- **THEN** the tool returns a list with both candidates, each carrying a distinct id and distinct folder path
-
-#### Scenario: No match returns empty list
-- **WHEN** `resolve_name` is called with a query that matches no entity of the requested type
-- **THEN** the tool returns an empty list and does not throw an error
-
-#### Scenario: Path-qualified query narrows scope
-- **WHEN** `resolve_name` is called with `{type: "folder", query: "Acme", scope: "Work ▸ Clients"}`
-- **THEN** the tool returns only folders named "Acme" that are direct or transitive children of the folder at path "Work ▸ Clients"
-
-### Requirement: Folder path addressing
-
-The system SHALL represent folder paths as strings using the separator ` ▸ ` (U+25B8 with surrounding spaces) and SHALL support resolving a folder by its full path as an alternative to its ID. When a path is ambiguous (the same path exists under multiple roots, which cannot occur for folders but can for tags), the resolution SHALL report the ambiguity through `resolve_name`.
-
-#### Scenario: Folder resolves by full path
-- **WHEN** `resolve_name` is called with `{type: "folder", query: "Work ▸ Clients ▸ Acme"}`
-- **THEN** the tool returns the folder whose full ancestor chain matches that path exactly
-
-#### Scenario: Returned paths use the canonical separator
-- **WHEN** any read tool returns a folder path or a project's containing folder path
-- **THEN** the path uses ` ▸ ` as the separator between ancestor names

package/openspec/changes/archive/2026-04-09-bootstrap-omnifocus-mcp/specs/perspective-management/spec.md

@@ -1,9 +0,0 @@
-## ADDED Requirements
-
-### Requirement: Capability declared
-
-The `perspective-management` capability SHALL cover listing built-in and custom perspectives, reading perspective metadata, and activating a perspective in a document window. Custom perspective *creation and editing* are a non-goal pending verification of OmniJS scriptability of `Perspective.Custom` definitions; if a future investigation proves the API is available, the non-goal may be revisited by a later change. Requirements for individual tools SHALL be added by the `perspectives-and-windows` change.
-
-#### Scenario: Capability is named and scoped
-- **WHEN** a future change proposes adding perspective tools
-- **THEN** it lands requirements under this capability rather than inventing a new capability name

package/openspec/changes/archive/2026-04-09-bootstrap-omnifocus-mcp/specs/project-management/spec.md

@@ -1,25 +0,0 @@
-## ADDED Requirements
-
-### Requirement: List projects
-
-The system SHALL provide a `list_projects` tool that returns every project in the OmniFocus database as an array of summaries, each containing at minimum `{id, name, folderPath, status, type}`. 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 projects at the top level with no containing folder.
-
-#### Scenario: All projects are returned with canonical fields
-- **WHEN** `list_projects` is called with no arguments
-- **THEN** the tool returns every project in the database, each with id, name, folderPath, status, and type populated using the canonical enum values
-
-#### 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"`
-
-### Requirement: Get project by ID
-
-The system SHALL provide a `get_project` tool that accepts `{id: string}` and returns the full detail record of the named project, including `{id, name, note, folderPath, status, type, flagged, deferDate, dueDate, completionDate, reviewInterval, nextReviewDate, lastReviewDate, tagIds}`. If no project exists with that ID, the tool SHALL return a structured not-found error.
-
-#### Scenario: Existing project returns full detail
-- **WHEN** `get_project` is called with the ID of an existing project
-- **THEN** the tool returns the project's full detail record
-
-#### Scenario: Missing project returns not-found error
-- **WHEN** `get_project` is called with an ID that does not correspond to any project
-- **THEN** the tool returns a structured error with a not-found code

package/openspec/changes/archive/2026-04-09-bootstrap-omnifocus-mcp/specs/recurrence/spec.md

@@ -1,9 +0,0 @@
-## ADDED Requirements
-
-### Requirement: Capability declared
-
-The `recurrence` capability SHALL cover the construction, assignment, reading, and clearing of `Task.RepetitionRule` values on OmniFocus tasks, including the `RepetitionMethod` (`Fixed`, `DueDate`, `Start`, `None`) and the underlying ICS RRULE string. Tools under this capability SHALL expose both a structured schema for common recurrence patterns (frequency, interval, weekday set) and a raw `rrule` escape hatch for patterns the structured schema does not express. Requirements for individual tools SHALL be added by the `recurrence` change. This change only declares the capability and its scope.
-
-#### Scenario: Capability is named and scoped
-- **WHEN** a future change proposes adding recurrence-related tools
-- **THEN** it lands requirements under this capability rather than inventing a new capability name

package/openspec/changes/archive/2026-04-09-bootstrap-omnifocus-mcp/specs/settings/spec.md

@@ -1,9 +0,0 @@
-## ADDED Requirements
-
-### Requirement: Capability declared
-
-The `settings` capability SHALL cover reading OmniFocus application settings and preferences where the OmniJS API exposes them. Write access SHALL be limited to the subset of settings that OmniJS documents as writable; the specific writable keys SHALL be enumerated when the `settings` change is drafted. Requirements for individual tools SHALL be added by that change.
-
-#### Scenario: Capability is named and scoped
-- **WHEN** a future change proposes adding settings tools
-- **THEN** it lands requirements under this capability, with an explicit enumeration of writable keys vs read-only keys

package/openspec/changes/archive/2026-04-09-bootstrap-omnifocus-mcp/specs/tag-management/spec.md

@@ -1,25 +0,0 @@
-## ADDED Requirements
-
-### Requirement: List tags
-
-The system SHALL provide a `list_tags` tool that returns every tag in the OmniFocus database as an array of summaries, each containing at minimum `{id, name, path, parentId, status}`. Tags form a tree in OmniFocus; the `path` field SHALL use the canonical ` ▸ ` separator and represent the full ancestor chain. The `parentId` field SHALL be `null` for top-level tags. The `status` field SHALL be one of `"active" | "onHold" | "dropped"`.
-
-#### Scenario: All tags are returned including nested tags
-- **WHEN** `list_tags` is called with no arguments
-- **THEN** the tool returns every tag in the database, top-level and nested, each with its full path and correct parentId
-
-#### Scenario: On-hold tag is reported with correct status
-- **WHEN** the database contains a tag that has been placed on hold
-- **THEN** that tag appears in the result with `status: "onHold"`
-
-### Requirement: Get tag by ID
-
-The system SHALL provide a `get_tag` tool that accepts `{id: string}` and returns the full detail record of the named tag, including `{id, name, path, parentId, status, childTagIds}`. If no tag exists with that ID, the tool SHALL return a structured not-found error.
-
-#### Scenario: Existing tag returns full detail
-- **WHEN** `get_tag` is called with the ID of an existing tag
-- **THEN** the tool returns the tag's full detail including the IDs of its immediate child tags
-
-#### Scenario: Missing tag returns not-found error
-- **WHEN** `get_tag` is called with an ID that does not correspond to any tag
-- **THEN** the tool returns a structured error with a not-found code

package/openspec/changes/archive/2026-04-09-bootstrap-omnifocus-mcp/specs/task-management/spec.md

@@ -1,29 +0,0 @@
-## ADDED 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 return an array of task summaries, each containing at minimum `{id, name, status, flagged, containerId, containerType}`.
-
-#### Scenario: List tasks in a specific project
-- **WHEN** `list_tasks` is called with `{projectId: "abc123"}`
-- **THEN** the tool returns every task directly or transitively contained in that project, with each element 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 every task in the OmniFocus inbox 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
-
-### 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}`. 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 and the list of tag IDs assigned to it
-
-#### 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-bootstrap-omnifocus-mcp/specs/url-automation/spec.md

@@ -1,9 +0,0 @@
-## ADDED Requirements
-
-### Requirement: Capability declared
-
-The `url-automation` capability SHALL cover `omnifocus://` URL construction (including task-paste format for bulk creation, add-to-inbox URLs, and deep links to entities by ID) and parsing of incoming `omnifocus://` URLs into structured form. Requirements for individual tools SHALL be added by the `url-automation` change.
-
-#### Scenario: Capability is named and scoped
-- **WHEN** a future change proposes adding URL-automation tools
-- **THEN** it lands requirements under this capability rather than inventing a new capability name

package/openspec/changes/archive/2026-04-09-bootstrap-omnifocus-mcp/specs/window-state/spec.md

@@ -1,9 +0,0 @@
-## ADDED Requirements
-
-### Requirement: Capability declared
-
-The `window-state` capability SHALL cover read-only inspection of OmniFocus document window state, including the currently active window, active perspective, sidebar selection, and content selection. Window *mutation* (resize, close, focus, open) is an explicit non-goal. Requirements for individual tools SHALL be added by the `perspectives-and-windows` change.
-
-#### Scenario: Capability is named and read-only scope is fixed
-- **WHEN** a future change proposes adding window-state tools
-- **THEN** it lands read-only requirements under this capability; any mutation proposal requires first revisiting the non-goal in design

package/openspec/changes/archive/2026-04-09-bootstrap-omnifocus-mcp/tasks.md

@@ -1,84 +0,0 @@
-## 1. Repository scaffold
-
-- [x] 1.1 Create `package.json` with dependencies: `@modelcontextprotocol/sdk`, `zod`; devDependencies: `typescript`, `vitest`, `@types/node`, `tsx`
-- [x] 1.2 Create `tsconfig.json` targeting Node 20, strict mode, `moduleResolution: "bundler"`, `outDir: "dist"`, sourcemaps on
-- [x] 1.3 Create directory structure: `src/runtime/`, `src/snippets/`, `src/tools/`, `src/schemas/`, `test/unit/`, `test/integration/`
-- [x] 1.4 Add `.gitignore` covering `node_modules`, `dist`, `*.log`, macOS cruft
-- [x] 1.5 Add root `README.md` stub with macOS-only note and integration-test warning about sync
-
-## 2. Execution runtime (src/runtime/)
-
-- [x] 2.1 Implement `snippetLoader.ts`: reads `src/snippets/<name>.js` from the resolved snippet root, caches in memory, validates exactly one `__ARGS__` token, throws on zero or multiple
-- [x] 2.2 Implement `resultProtocol.ts`: zod schema for the `{ok, data} | {ok: false, error}` envelope, `parseResultLine(stdout: string)` that selects the first JSON-parseable line and validates the envelope, `ExecutionError` class carrying name/message/stack from the error branch
-- [x] 2.3 Implement `jxaShim.ts`: a template string containing the JXA wrapper that calls `Application('OmniFocus').evaluateJavascript(snippet)`, wraps in try/catch, prints the envelope as one JSON line
-- [x] 2.4 Implement `bridge.ts`: `runSnippet(name: string, args: unknown, opts?: {timeoutMs?: number}): Promise<unknown>` — loads the snippet via the loader, injects args via `template.replace("__ARGS__", JSON.stringify(args))`, wraps the result in the JXA shim, spawns `osascript -l JavaScript`, enforces timeout via `AbortController` + SIGTERM, parses stdout via `parseResultLine`, throws `ExecutionError` on `ok: false`, returns `data` on success
-- [x] 2.5 Export a single `runtime` barrel from `src/runtime/index.ts`
-
-## 3. Shared schemas (src/schemas/)
-
-- [x] 3.1 Define zod schemas: `IdSchema` (non-empty string), `EntityType` enum (`"task" | "project" | "folder" | "tag" | "perspective"`), `ProjectType` enum, `ProjectStatus` enum, `TaskStatus` enum, `TagStatus` enum, `FolderStatus` enum
-- [x] 3.2 Define shared return-shape schemas: `TaskSummary`, `TaskDetail`, `ProjectSummary`, `ProjectDetail`, `FolderSummary`, `FolderDetail`, `TagSummary`, `TagDetail`, `ResolveCandidate`
-- [x] 3.3 Export a `schemas` barrel from `src/schemas/index.ts`
-
-## 4. Snippets (src/snippets/*.js) — read-only set for this change
-
-- [x] 4.1 `list_projects.js`: iterate `flattenedProjects`, map to summary shape with `id.primaryKey`, canonical `status`/`type` enum values, folder path via ` ▸ ` separator; return `JSON.stringify({ok: true, data: [...]})`
-- [x] 4.2 `get_project.js`: resolve project by `args.id` via `Project.byIdentifier` (or equivalent), build detail shape including review metadata and tag IDs, return envelope; throw on not-found with a `NotFoundError` constructor defined at the top of the snippet
-- [x] 4.3 `list_folders.js`: iterate `flattenedFolders`, map to summary with full path; return envelope
-- [x] 4.4 `get_folder.js`: resolve folder by ID, return detail including child folder IDs and immediate project IDs
-- [x] 4.5 `list_tasks.js`: accept `args.scope` discriminated union (`projectId` / `folderId` / `inbox` / `all`), iterate the correct source, map to summary; return envelope
-- [x] 4.6 `get_task.js`: resolve task by ID, return full detail including tag IDs
-- [x] 4.7 `list_tags.js`: iterate `flattenedTags`, map to summary with full path, parentId, status
-- [x] 4.8 `get_tag.js`: resolve tag by ID, return detail including child tag IDs
-- [x] 4.9 `resolve_name.js`: accept `args.type`, `args.query`, optional `args.scope`; walk the relevant flat list, match by exact name (and path suffix if scope given), return array of candidates with `{id, name, path, type}`; never throw on zero matches
-- [x] 4.10 Add a shared helper comment block at the top of each snippet documenting the paste-to-console procedure
-
-## 5. MCP tools (src/tools/)
-
-- [x] 5.1 `listProjects.ts`: zod input schema (empty object), handler invokes `runSnippet("list_projects", {})`, validates output against `z.array(ProjectSummary)`, returns
-- [x] 5.2 `getProject.ts`: input `{id}`, handler invokes `runSnippet("get_project", {id})`, validates `ProjectDetail`
-- [x] 5.3 `listFolders.ts`: empty input, returns `z.array(FolderSummary)`
-- [x] 5.4 `getFolder.ts`: input `{id}`, returns `FolderDetail`
-- [x] 5.5 `listTasks.ts`: input discriminated union (`{projectId} | {folderId} | {inbox: true} | {all: true}`) with zod `discriminatedUnion` or refinement rejecting mutual exclusivity, returns `z.array(TaskSummary)`
-- [x] 5.6 `getTask.ts`: input `{id}`, returns `TaskDetail`
-- [x] 5.7 `listTags.ts`: empty input, returns `z.array(TagSummary)`
-- [x] 5.8 `getTag.ts`: input `{id}`, returns `TagDetail`
-- [x] 5.9 `resolveName.ts`: input `{type, query, scope?}`, returns `z.array(ResolveCandidate)`
-- [x] 5.10 Export a `tools` barrel from `src/tools/index.ts` listing all nine tool definitions
-
-## 6. MCP server entrypoint
-
-- [x] 6.1 `src/server.ts`: construct an `@modelcontextprotocol/sdk` server, register all nine tools from the barrel, wire stdio transport, start listening
-- [x] 6.2 Add `bin` field to `package.json` pointing at the compiled entrypoint and a `scripts.start` for development via `tsx`
-
-## 7. Unit tests (test/unit/)
-
-- [x] 7.1 `snippetLoader.test.ts`: golden-file test that loading each snippet in `src/snippets/` succeeds and contains exactly one `__ARGS__`; contract-violation tests for zero/multiple placeholders (using fixture files)
-- [x] 7.2 `resultProtocol.test.ts`: parses well-formed success envelope, parses well-formed error envelope, rejects malformed JSON, selects first parseable line when preceded by chatter
-- [x] 7.3 `bridge.injection.test.ts`: given a snippet template and args containing apostrophes, quotes, backslashes, newlines, and emoji, assert the generated script source is valid JavaScript (parse via `new Function`) and that evaluating it recovers the original args object unchanged — proves Decision 2 structurally
-- [x] 7.4 `schemas.test.ts`: round-trip validation for each shared schema; rejection tests for the `sequential`-as-string and `items`-as-JSON-string regression patterns at the boundary
-- [x] 7.5 `tools.listTasks.test.ts`: rejects mutually exclusive scope combinations at the zod boundary before any bridge call
-
-## 8. Integration test harness (test/integration/)
-
-- [x] 8.1 `fixtures.ts`: `createTestFolder()` generates `__MCP_TEST_<uuid>__` top-level folder via the bridge; `cleanupTestFolder(id)` removes it; `withTestFolder(fn)` helper wraps a test body
-- [x] 8.2 `preflight.ts`: detects OmniFocus sync status (via a read-only snippet that inspects the relevant setting); throws unless `MCP_TEST_ALLOW_SYNC=1` is set; invoked once in the vitest global setup
-- [x] 8.3 `vitest.integration.config.ts`: separate vitest config for integration with `pool: "forks"`, `maxConcurrency: 1`, `globalSetup: ./preflight.ts`, `testMatch: test/integration/**`
-- [x] 8.4 Integration test: `listProjects.int.test.ts` creates a fixture folder with a child project, calls the real bridge, asserts the fixture project appears in the result with the correct folder path
-- [x] 8.5 Integration test: `getTask.int.test.ts` creates a fixture task with an apostrophe and unicode in its name, retrieves by ID, asserts name survives round-trip — proves Decision 2 end-to-end
-- [x] 8.6 Integration test: `resolveName.int.test.ts` creates two fixture projects with identical names under different folders, asserts `resolve_name` returns both candidates with distinct paths
-- [x] 8.7 Add a `scripts.test:integration` in `package.json` guarded by macOS check
-- [x] 8.8 Add a `scripts.test:cleanup-fixtures` that scans for stale `__MCP_TEST_*` folders and removes them
-
-## 9. Documentation
-
-- [x] 9.1 Expand `README.md` with: prerequisites (macOS, OmniFocus running), install, MCP client configuration snippet, the list of tools delivered in this change, the loud warning about integration tests mutating real data and the sync preflight
-- [x] 9.2 Add `CONTRIBUTING.md` documenting the snippet authoring rules (the `__ARGS__` placeholder, no other interpolation, paste-to-console workflow) and the forbidden-scripting-dictionary rule from execution-runtime spec
-
-## 10. Verification
-
-- [x] 10.1 Run `npm run typecheck` (or `tsc --noEmit`) clean
-- [x] 10.2 Run `npm run test` (unit suite) clean
-- [x] 10.3 Manually run integration suite against a real OmniFocus with sync disabled; verify fixture folder is created and torn down
-- [x] 10.4 Manually connect the server to an MCP client (Claude Desktop or equivalent) and invoke each of the nine tools against a real database; verify results match the spec scenarios
-- [x] 10.5 Confirm all spec scenarios in `specs/execution-runtime/spec.md` and `specs/identity-resolution/spec.md` have corresponding test coverage (unit + integration)

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

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

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

@@ -1,58 +0,0 @@
-## Context
-
-Folders in OmniJS are simpler than tasks or projects — they have only `name` and `status` as meaningful writable properties, and they nest via parent/child relationships. The main complexity is deletion: `deleteObject(folder)` leaves an empty shell (as discovered during bootstrap integration testing); the snippet must recursively delete contents first.
-
-OmniJS folder write operations:
-- `new Folder(name)` — creates a top-level folder (auto-inserted at root)
-- `new Folder(name, folderObject)` — creates a nested folder inside `folderObject`
-- `folder.name = "..."` — rename
-- `deleteObject(folder)` — removes folder shell but NOT contents; must delete contents first
-- Recursive deletion pattern (established in bootstrap fixtures): delete all projects in folder, recurse child folders, then delete the folder itself
-
-## Goals / Non-Goals
-
-**Goals:**
-- Create top-level and nested folders
-- Rename folders
-- Delete folders with full recursive cascade (projects, tasks, child folders)
-
-**Non-Goals:**
-- Moving a folder to a different parent (separate `move-operations` change)
-- Changing folder status directly (OmniFocus manages active/dropped based on contents)
-
-## Decisions
-
-### Decision 1: Recursive deletion in the snippet
-
-The snippet for `delete_folder` must implement recursive deletion rather than relying on `deleteObject` to cascade. The pattern is:
-
-```
-function deleteFolder(f) {
-  f.flattenedProjects.forEach(p => deleteObject(p));
-  f.folders.forEach(child => deleteFolder(child));
-  deleteObject(f);
-}
-```
-
-This was validated during bootstrap integration testing (`fixtures.ts` uses this exact pattern).
-
-### Decision 2: `create_folder` placement via optional `parentFolderId`
-
-- `parentFolderId` omitted → top-level folder
-- `parentFolderId` provided → nested inside that folder
-
-`new Folder(name)` for top-level; `new Folder(name, parentFolder)` for nested. Snippet resolves the parent by ID.
-
-### Decision 3: No `edit_folder` status field
-
-Folder status (`active` / `dropped`) in OmniFocus reflects whether the folder has active contents — it is not directly user-settable in the same way as project status. `edit_folder` exposes only `name`. If this proves insufficient in practice it can be extended.
-
-### Decision 4: `delete_folder` tool description is the strongest warning in the server
-
-This is the most destructive single operation: one call can delete an entire project hierarchy. The tool description must explicitly state that all child folders, projects, and tasks are permanently deleted, and that the AI must confirm with the user before calling it.
-
-## Risks / Trade-offs
-
-- **`deleteObject` on folder leaves shell** — confirmed behavior; recursive snippet pattern mitigates this fully.
-- **Deleting a folder containing hundreds of projects** — could be slow inside `evaluateJavascript`; the 30s timeout applies. Not worth special-casing in v1.
-- **Race between read and delete** — if the user reads a folder ID then calls delete, OmniFocus has no transaction isolation. Acceptable for a single-user desktop app.

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

@@ -1,28 +0,0 @@
-## Why
-
-The bootstrap change delivered read-only folder access. Callers can traverse the folder hierarchy but cannot create, rename, or delete folders — blocking any workflow that involves organizing projects into folders.
-
-## What Changes
-
-- Add `create_folder` tool: create a folder at the top level or nested inside an existing folder
-- Add `edit_folder` tool: rename a folder
-- Add `delete_folder` tool: permanently delete a folder and all its contents — projects, tasks, and child folders (tool description instructs the AI to confirm with the user before invoking and calls out the destructive cascade)
-
-## Capabilities
-
-### New Capabilities
-
-- `folder-write`: Create, rename, and permanently delete OmniFocus folders
-
-### Modified Capabilities
-
-_(none — existing `folder-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
-- Integration tests will mutate real OmniFocus data (scoped to fixture folder per existing pattern)
-- `delete_folder` is the most destructive single operation in the server — the tool description warrants an explicit warning that the entire subtree (child folders, projects, and all tasks) is permanently removed

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

@@ -1,45 +0,0 @@
-## ADDED Requirements
-
-### Requirement: Create folder
-
-The system SHALL provide a `create_folder` tool that creates a new OmniFocus folder and returns its full detail record. The tool SHALL accept `{name: string, parentFolderId?: string}`. If `parentFolderId` is provided the folder SHALL be created nested inside that folder; otherwise it SHALL be created at the top level.
-
-#### Scenario: Create top-level folder
-- **WHEN** `create_folder` is called with `{name: "Work"}` and no `parentFolderId`
-- **THEN** the tool creates the folder at the top level and returns its full detail record including a stable `id`
-
-#### Scenario: Create nested folder
-- **WHEN** `create_folder` is called with `{name: "Active", parentFolderId: "abc123"}`
-- **THEN** the tool creates the folder inside the specified parent folder and returns its full detail record with `path` reflecting the full ancestor chain
-
-#### Scenario: Non-existent parent folder returns not-found error
-- **WHEN** `create_folder` is called with a `parentFolderId` that does not correspond to any folder
-- **THEN** the tool returns a structured not-found error
-
-### Requirement: Edit folder
-
-The system SHALL provide an `edit_folder` tool that renames an existing folder and returns its updated full detail record. The tool SHALL accept `{id: string, name: string}`.
-
-#### Scenario: Rename a folder
-- **WHEN** `edit_folder` is called with `{id: "abc123", name: "Personal"}`
-- **THEN** the folder's name is updated and the tool returns the updated detail record with the new name reflected in `path`
-
-#### Scenario: Non-existent folder returns not-found error
-- **WHEN** `edit_folder` is called with an ID that does not correspond to any folder
-- **THEN** the tool returns a structured not-found error
-
-### Requirement: Delete folder
-
-The system SHALL provide a `delete_folder` tool that permanently and recursively deletes a folder, all child folders, all projects within those folders, and all tasks within those projects. The tool description SHALL instruct the AI to confirm with the user before invoking, explicitly stating that the entire subtree — child folders, projects, and all tasks — is permanently deleted and cannot be undone.
-
-#### Scenario: Delete a folder and all its contents
-- **WHEN** `delete_folder` is called with the ID of an existing folder
-- **THEN** the folder, all descendant folders, all projects within those folders, and all tasks within those projects are permanently removed from OmniFocus and the tool returns a confirmation envelope
-
-#### Scenario: Delete empty folder
-- **WHEN** `delete_folder` is called with the ID of a folder that contains no projects or child folders
-- **THEN** the folder is removed and the tool returns a confirmation envelope
-
-#### Scenario: Non-existent folder returns not-found error
-- **WHEN** `delete_folder` is called with an ID that does not correspond to any folder
-- **THEN** the tool returns a structured not-found error

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

@@ -1,41 +0,0 @@
-## 1. Snippets (src/snippets/)
-
-- [x] 1.1 `create_folder.js`: accept `{name, parentFolderId?}`; if `parentFolderId` provided resolve parent by ID and throw `NotFoundError` if missing; create `new Folder(name)` or `new Folder(name, parentFolder)`; return full folder detail envelope
-- [x] 1.2 `edit_folder.js`: accept `{id, name}`; resolve folder by ID; assign `folder.name = name`; return updated full folder detail envelope
-- [x] 1.3 `delete_folder.js`: accept `{id}`; resolve folder by ID; recursively delete contents (projects then child folders) then `deleteObject(folder)`; return `{ok: true, data: {id}}`
-
-## 2. Snippet allowlist
-
-- [x] 2.1 Add `create_folder`, `edit_folder`, `delete_folder` to `ALLOWED_SNIPPETS` in `src/runtime/snippetLoader.ts`
-
-## 3. Schemas (src/schemas/shapes.ts)
-
-- [x] 3.1 Define `CreateFolderInput` zod schema: `{name: z.string().min(1), parentFolderId: IdSchema.optional()}`
-- [x] 3.2 Define `EditFolderInput` zod schema: `{id: IdSchema, name: z.string().min(1)}`
-
-## 4. Tool handlers (src/tools/)
-
-- [x] 4.1 `createFolder.ts`: validate input with `CreateFolderInput`; invoke `runSnippet("create_folder", args)`; validate result against `FolderDetail`; return
-- [x] 4.2 `editFolder.ts`: validate input with `EditFolderInput`; invoke `runSnippet("edit_folder", args)`; validate result against `FolderDetail`; return
-- [x] 4.3 `deleteFolder.ts`: input `{id: IdSchema}`; tool description MUST state the AI should confirm with the user before invoking and explicitly note that the entire subtree — child folders, projects, and all tasks — is permanently deleted; invoke `runSnippet("delete_folder", {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.createFolder.test.ts`: valid inputs pass; empty name rejected
-
-## 7. Integration tests (test/integration/)
-
-- [x] 7.1 `createFolder.int.test.ts`: create top-level folder; create nested folder; verify `path` and `parentId`
-- [x] 7.2 `editFolder.int.test.ts`: rename a folder; verify `name` and `path` updated
-- [x] 7.3 `deleteFolder.int.test.ts`: create folder with child project and tasks; delete folder; verify `get_folder` returns not-found and projects are 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-folder-tag-list-filtering/.openspec.yaml

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

package/openspec/changes/archive/2026-04-09-folder-tag-list-filtering/design.md

@@ -1,38 +0,0 @@
-## Context
-
-`list_folders` and `list_tags` are the last two list tools without filtering or limit support. The pattern established by `list_tasks` and `list_projects` — filter inside the OmniJS snippet, expose filter object and limit from the TypeScript handler — applies directly.
-
-Unlike tasks and projects, there is no universally agreed "terminal" status for folders (dropped folders are unusual but valid to show) or tags (onHold tags are actively used). Therefore the default behavior includes all statuses; filtering is opt-in.
-
-## Goals / Non-Goals
-
-**Goals:**
-- `list_folders`: add `limit` (default 200) and optional `status` filter (`active` | `dropped`)
-- `list_tags`: add `limit` (default 200) and optional `status` filter (`active` | `onHold` | `dropped`)
-
-**Non-Goals:**
-- `parentId` / subtree scoping for folders or tags (flat list is sufficient in practice)
-- Filtering by name or path pattern
-- Pagination
-
-## Decisions
-
-### Decision 1: No default status exclusion
-
-Unlike `list_tasks` and `list_projects`, the default returns all statuses. Dropped folders/tags are uncommon enough that including them doesn't overwhelm results, and an LLM may need to see them. Callers can pass `status: ["active"]` to filter.
-
-### Decision 2: Single status value, not array
-
-For `list_folders` and `list_tags`, a single `status` string (not an array) is sufficient — users rarely need "active OR onHold" for tags. Simpler API. If multi-status becomes needed, it's a non-breaking addition later.
-
-### Decision 3: Limit default 200
-
-Folders and tags are fewer than tasks; 200 is generous. Consistent with the spirit of existing defaults (tasks: 200, projects: 100).
-
-### Decision 4: Same filter-in-snippet pattern
-
-All filtering in the OmniJS snippet before data crosses the JXA bridge. TypeScript layer validates and passes through. Consistent with list_tasks and list_projects.
-
-## Risks / Trade-offs
-
-- **Minimal risk** — purely additive. Existing callers passing no args get all items (same as before but now capped at 200, which is a minor behavior change). Acceptable.