@scardis/omnifocus-mcp 0.1.0 → 0.1.2

package/.claude/skills/openspec-sync-specs/SKILL.md

@@ -1,138 +0,0 @@
----
-name: openspec-sync-specs
-description: Sync delta specs from a change to main specs. Use when the user wants to update main specs with changes from a delta spec, without archiving the change.
-license: MIT
-compatibility: Requires openspec CLI.
-metadata:
-  author: openspec
-  version: "1.0"
-  generatedBy: "1.2.0"
----
-
-Sync delta specs from a change to main specs.
-
-This is an **agent-driven** operation - you will read delta specs and directly edit main specs to apply the changes. This allows intelligent merging (e.g., adding a scenario without copying the entire requirement).
-
-**Input**: Optionally specify a change name. If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.
-
-**Steps**
-
-1. **If no change name provided, prompt for selection**
-
-   Run `openspec list --json` to get available changes. Use the **AskUserQuestion tool** to let the user select.
-
-   Show changes that have delta specs (under `specs/` directory).
-
-   **IMPORTANT**: Do NOT guess or auto-select a change. Always let the user choose.
-
-2. **Find delta specs**
-
-   Look for delta spec files in `openspec/changes/<name>/specs/*/spec.md`.
-
-   Each delta spec file contains sections like:
-   - `## ADDED Requirements` - New requirements to add
-   - `## MODIFIED Requirements` - Changes to existing requirements
-   - `## REMOVED Requirements` - Requirements to remove
-   - `## RENAMED Requirements` - Requirements to rename (FROM:/TO: format)
-
-   If no delta specs found, inform user and stop.
-
-3. **For each delta spec, apply changes to main specs**
-
-   For each capability with a delta spec at `openspec/changes/<name>/specs/<capability>/spec.md`:
-
-   a. **Read the delta spec** to understand the intended changes
-
-   b. **Read the main spec** at `openspec/specs/<capability>/spec.md` (may not exist yet)
-
-   c. **Apply changes intelligently**:
-
-      **ADDED Requirements:**
-      - If requirement doesn't exist in main spec → add it
-      - If requirement already exists → update it to match (treat as implicit MODIFIED)
-
-      **MODIFIED Requirements:**
-      - Find the requirement in main spec
-      - Apply the changes - this can be:
-        - Adding new scenarios (don't need to copy existing ones)
-        - Modifying existing scenarios
-        - Changing the requirement description
-      - Preserve scenarios/content not mentioned in the delta
-
-      **REMOVED Requirements:**
-      - Remove the entire requirement block from main spec
-
-      **RENAMED Requirements:**
-      - Find the FROM requirement, rename to TO
-
-   d. **Create new main spec** if capability doesn't exist yet:
-      - Create `openspec/specs/<capability>/spec.md`
-      - Add Purpose section (can be brief, mark as TBD)
-      - Add Requirements section with the ADDED requirements
-
-4. **Show summary**
-
-   After applying all changes, summarize:
-   - Which capabilities were updated
-   - What changes were made (requirements added/modified/removed/renamed)
-
-**Delta Spec Format Reference**
-
-```markdown
-## ADDED Requirements
-
-### Requirement: New Feature
-The system SHALL do something new.
-
-#### Scenario: Basic case
-- **WHEN** user does X
-- **THEN** system does Y
-
-## MODIFIED Requirements
-
-### Requirement: Existing Feature
-#### Scenario: New scenario to add
-- **WHEN** user does A
-- **THEN** system does B
-
-## REMOVED Requirements
-
-### Requirement: Deprecated Feature
-
-## RENAMED Requirements
-
-- FROM: `### Requirement: Old Name`
-- TO: `### Requirement: New Name`
-```
-
-**Key Principle: Intelligent Merging**
-
-Unlike programmatic merging, you can apply **partial updates**:
-- To add a scenario, just include that scenario under MODIFIED - don't copy existing scenarios
-- The delta represents *intent*, not a wholesale replacement
-- Use your judgment to merge changes sensibly
-
-**Output On Success**
-
-```
-## Specs Synced: <change-name>
-
-Updated main specs:
-
-**<capability-1>**:
-- Added requirement: "New Feature"
-- Modified requirement: "Existing Feature" (added 1 scenario)
-
-**<capability-2>**:
-- Created new spec file
-- Added requirement: "Another Feature"
-
-Main specs are now updated. The change remains active - archive when implementation is complete.
-```
-
-**Guardrails**
-- Read both delta and main specs before making changes
-- Preserve existing content not mentioned in delta
-- If something is unclear, ask for clarification
-- Show what you're changing as you go
-- The operation should be idempotent - running twice should give same result

package/.claude/skills/openspec-verify-change/SKILL.md

@@ -1,168 +0,0 @@
----
-name: openspec-verify-change
-description: Verify implementation matches change artifacts. Use when the user wants to validate that implementation is complete, correct, and coherent before archiving.
-license: MIT
-compatibility: Requires openspec CLI.
-metadata:
-  author: openspec
-  version: "1.0"
-  generatedBy: "1.2.0"
----
-
-Verify that an implementation matches the change artifacts (specs, tasks, design).
-
-**Input**: Optionally specify a change name. If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.
-
-**Steps**
-
-1. **If no change name provided, prompt for selection**
-
-   Run `openspec list --json` to get available changes. Use the **AskUserQuestion tool** to let the user select.
-
-   Show changes that have implementation tasks (tasks artifact exists).
-   Include the schema used for each change if available.
-   Mark changes with incomplete tasks as "(In Progress)".
-
-   **IMPORTANT**: Do NOT guess or auto-select a change. Always let the user choose.
-
-2. **Check status to understand the schema**
-   ```bash
-   openspec status --change "<name>" --json
-   ```
-   Parse the JSON to understand:
-   - `schemaName`: The workflow being used (e.g., "spec-driven")
-   - Which artifacts exist for this change
-
-3. **Get the change directory and load artifacts**
-
-   ```bash
-   openspec instructions apply --change "<name>" --json
-   ```
-
-   This returns the change directory and context files. Read all available artifacts from `contextFiles`.
-
-4. **Initialize verification report structure**
-
-   Create a report structure with three dimensions:
-   - **Completeness**: Track tasks and spec coverage
-   - **Correctness**: Track requirement implementation and scenario coverage
-   - **Coherence**: Track design adherence and pattern consistency
-
-   Each dimension can have CRITICAL, WARNING, or SUGGESTION issues.
-
-5. **Verify Completeness**
-
-   **Task Completion**:
-   - If tasks.md exists in contextFiles, read it
-   - Parse checkboxes: `- [ ]` (incomplete) vs `- [x]` (complete)
-   - Count complete vs total tasks
-   - If incomplete tasks exist:
-     - Add CRITICAL issue for each incomplete task
-     - Recommendation: "Complete task: <description>" or "Mark as done if already implemented"
-
-   **Spec Coverage**:
-   - If delta specs exist in `openspec/changes/<name>/specs/`:
-     - Extract all requirements (marked with "### Requirement:")
-     - For each requirement:
-       - Search codebase for keywords related to the requirement
-       - Assess if implementation likely exists
-     - If requirements appear unimplemented:
-       - Add CRITICAL issue: "Requirement not found: <requirement name>"
-       - Recommendation: "Implement requirement X: <description>"
-
-6. **Verify Correctness**
-
-   **Requirement Implementation Mapping**:
-   - For each requirement from delta specs:
-     - Search codebase for implementation evidence
-     - If found, note file paths and line ranges
-     - Assess if implementation matches requirement intent
-     - If divergence detected:
-       - Add WARNING: "Implementation may diverge from spec: <details>"
-       - Recommendation: "Review <file>:<lines> against requirement X"
-
-   **Scenario Coverage**:
-   - For each scenario in delta specs (marked with "#### Scenario:"):
-     - Check if conditions are handled in code
-     - Check if tests exist covering the scenario
-     - If scenario appears uncovered:
-       - Add WARNING: "Scenario not covered: <scenario name>"
-       - Recommendation: "Add test or implementation for scenario: <description>"
-
-7. **Verify Coherence**
-
-   **Design Adherence**:
-   - If design.md exists in contextFiles:
-     - Extract key decisions (look for sections like "Decision:", "Approach:", "Architecture:")
-     - Verify implementation follows those decisions
-     - If contradiction detected:
-       - Add WARNING: "Design decision not followed: <decision>"
-       - Recommendation: "Update implementation or revise design.md to match reality"
-   - If no design.md: Skip design adherence check, note "No design.md to verify against"
-
-   **Code Pattern Consistency**:
-   - Review new code for consistency with project patterns
-   - Check file naming, directory structure, coding style
-   - If significant deviations found:
-     - Add SUGGESTION: "Code pattern deviation: <details>"
-     - Recommendation: "Consider following project pattern: <example>"
-
-8. **Generate Verification Report**
-
-   **Summary Scorecard**:
-   ```
-   ## Verification Report: <change-name>
-
-   ### Summary
-   | Dimension    | Status           |
-   |--------------|------------------|
-   | Completeness | X/Y tasks, N reqs|
-   | Correctness  | M/N reqs covered |
-   | Coherence    | Followed/Issues  |
-   ```
-
-   **Issues by Priority**:
-
-   1. **CRITICAL** (Must fix before archive):
-      - Incomplete tasks
-      - Missing requirement implementations
-      - Each with specific, actionable recommendation
-
-   2. **WARNING** (Should fix):
-      - Spec/design divergences
-      - Missing scenario coverage
-      - Each with specific recommendation
-
-   3. **SUGGESTION** (Nice to fix):
-      - Pattern inconsistencies
-      - Minor improvements
-      - Each with specific recommendation
-
-   **Final Assessment**:
-   - If CRITICAL issues: "X critical issue(s) found. Fix before archiving."
-   - If only warnings: "No critical issues. Y warning(s) to consider. Ready for archive (with noted improvements)."
-   - If all clear: "All checks passed. Ready for archive."
-
-**Verification Heuristics**
-
-- **Completeness**: Focus on objective checklist items (checkboxes, requirements list)
-- **Correctness**: Use keyword search, file path analysis, reasonable inference - don't require perfect certainty
-- **Coherence**: Look for glaring inconsistencies, don't nitpick style
-- **False Positives**: When uncertain, prefer SUGGESTION over WARNING, WARNING over CRITICAL
-- **Actionability**: Every issue must have a specific recommendation with file/line references where applicable
-
-**Graceful Degradation**
-
-- If only tasks.md exists: verify task completion only, skip spec/design checks
-- If tasks + specs exist: verify completeness and correctness, skip design
-- If full artifacts: verify all three dimensions
-- Always note which checks were skipped and why
-
-**Output Format**
-
-Use clear markdown with:
-- Table for summary scorecard
-- Grouped lists for issues (CRITICAL/WARNING/SUGGESTION)
-- Code references in format: `file.ts:123`
-- Specific, actionable recommendations
-- No vague suggestions like "consider reviewing"

package/CONTRIBUTING.md

@@ -1,83 +0,0 @@
-# Contributing
-
-## Snippet authoring rules
-
-Every OmniFocus operation in this server is implemented as a standalone `.js` file under `src/snippets/`. These rules are invariants — violating them causes the same class of bugs the server was built to eliminate.
-
-### Rule 1: One `__ARGS__` placeholder per snippet, no other interpolation
-
-Every snippet file must contain exactly one occurrence of the token `__ARGS__`. The runtime injects arguments by doing:
-
-```ts
-template.replace("__ARGS__", JSON.stringify(args))
-```
-
-This is the **only** way user-supplied data enters a snippet. No string concatenation, no template literals constructing JS source, no manual escaping. If you find yourself writing `"'"+someValue+"'"` or `` `const name = "${value}"` `` inside a snippet template, stop — that is the apostrophe/injection bug pattern this architecture was built to eliminate.
-
-Because `JSON.stringify` produces output that is a syntactic subset of JavaScript, the injected args literal is safe for all inputs including apostrophes, double quotes, backslashes, newlines, emoji, and arbitrary unicode.
-
-### Rule 2: Snippets must work standalone
-
-Every snippet must be paste-able into the OmniFocus Automation Console for manual testing. Replace `__ARGS__` with a hand-written object literal:
-
-```js
-// Paste this into OmniFocus Automation Console:
-const args = { id: "jMBMptE7rJ1" };
-// ... rest of the snippet
-```
-
-If your snippet cannot be tested this way, it's not a self-contained snippet — refactor until it is. This is what makes the snippets independently verifiable and debuggable.
-
-### Rule 3: Snippets return a JSON string in the result envelope format
-
-Every snippet's last expression must be a JSON string matching:
-
-```js
-JSON.stringify({ ok: true, data: <your result> })
-```
-
-On error, throw (don't return an error envelope) — the JXA shim catches the exception and constructs the error envelope automatically:
-
-```js
-// Good
-throw new Error("Project not found: " + args.id);
-
-// Don't do this — the shim handles it
-// return JSON.stringify({ ok: false, error: { ... } })
-```
-
-The one exception is inline error returns used to avoid the overhead of an exception for expected cases (like "not found" in a list operation). If you do this, use the same envelope shape:
-
-```js
-return JSON.stringify({ ok: false, error: { name: "NotFoundError", message: "..." } });
-```
-
-### Rule 4: No JXA scripting-dictionary domain methods
-
-The JXA shim uses `Application('OmniFocus').evaluateJavascript()` and nothing else. Inside snippets (which run in OmniJS), you have the full Omni Automation API: `flattenedProjects`, `flattenedTasks`, `flattenedFolders`, `flattenedTags`, `new Project(...)`, `new Folder(...)`, `moveTasks(...)`, etc.
-
-Do **not** use the JXA scripting dictionary for domain operations. Concretely, in the `src/runtime/jxaShim.ts` JXA wrapper, the only call to the OmniFocus application object is `evaluateJavascript`. In snippets themselves, there is no JXA application object — you're inside OmniJS already.
-
-This rule is why the server can do things the prior AppleScript-based server could not: folder creation, Single Actions lists, task moves, stable IDs, and recurrence rules all live in the OmniJS API, not the scripting dictionary.
-
-## Adding a new tool
-
-1. Write the OmniJS snippet as `src/snippets/<tool_name>.js`. Verify it works standalone in the Automation Console.
-2. Add the zod input schema and handler to `src/tools/<ToolName>.ts`.
-3. Export from `src/tools/index.ts` and add to `allTools`.
-4. Add the corresponding spec requirement and scenario to the relevant capability spec file under `openspec/changes/<change-name>/specs/<capability>/spec.md`.
-5. Write a unit test for schema validation and a unit test for injection safety if the tool has new parameter types.
-6. Write an integration test that exercises the tool against a real OmniFocus instance, scoped to a `withTestFolder` fixture.
-
-## Running tests
-
-```bash
-# Unit tests (no OmniFocus required)
-npm test
-
-# Integration tests (requires OmniFocus running on macOS)
-npm run test:integration
-
-# Clean up stale test fixtures from interrupted runs
-npm run test:cleanup-fixtures
-```

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

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

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

@@ -1,162 +0,0 @@
-## Context
-
-OmniFocus exposes two distinct automation surfaces on macOS:
-
-1. **The scripting dictionary**, reachable from AppleScript and JXA (`osascript -l JavaScript`). This is the legacy surface the prior MCP server targeted by generating AppleScript source strings. It lacks folder creation, Single Actions list type, task moves, stable IDs, and recurrence-rule construction. It also requires string-concatenation of arguments, which is the root cause of the apostrophe and name-ambiguity bug classes.
-
-2. **OmniJS**, the modern Omni Automation JavaScript runtime that lives *inside* the OmniFocus process. This is the API documented at omni-automation.com. It exposes `Task`, `Project`, `Folder`, `Tag`, `Task.RepetitionRule`, `Perspective`, `id.primaryKey`, `moveTasks`, `new Folder`, and everything else the prior server couldn't reach. It is reachable from outside OmniFocus *only* via the `evaluateJavascript` method on the scripting-dictionary application object.
-
-The two are not interchangeable. The scripting dictionary is a capability-limited facade over the same underlying database; OmniJS is the authoritative modern API. Every "cannot do X" limitation in the prior server is a limitation of the scripting dictionary, not of JXA or macOS automation generally.
-
-The project starts from a clean slate: no legacy code, no prior specs, no backwards-compatibility constraints. The only inputs are the Omni Automation API surface, the MCP protocol, and the enumerated failure modes of the prior server.
-
-## Goals / Non-Goals
-
-**Goals:**
-
-- Expose the full Omni Automation API surface through an MCP server, eventually reaching 1:1 coverage. This change establishes the foundation; subsequent changes fill in capabilities.
-- Eliminate by construction the bug classes of the prior server: apostrophe-breaking, name-ambiguity routing, parse-error-on-success, type-coercion failures in batch parameters, missing capability coverage.
-- Make every domain operation authored as a static, standalone `.js` snippet that can be pasted into OmniFocus's Automation Console for manual verification.
-- Provide stable, id-based addressing for every OmniFocus entity, with name/path resolution as a separate, explicit, ambiguity-reporting step.
-- Establish an integration-test harness that exercises a real OmniFocus instance without polluting the user's data or leaking fixtures across sync.
-- Name every target capability up front so future changes have a landing place and the scope of "full API coverage" is visible from the first commit.
-
-**Non-Goals:**
-
-- Cross-platform support. Omni Automation is macOS-only; the server is macOS-only.
-- Compatibility with the prior AppleScript-based MCP server. Tool names, parameter shapes, and result envelopes are all new.
-- Interactive UI automation: `Form`, `Alert`, `FilePicker`, `FileSaver`. These APIs require a human to click in the OmniFocus app while the script blocks; they cannot cross an MCP boundary without changing semantics.
-- Device-local side effects unrelated to OmniFocus data: `Speech`, `Device`, clipboard mutation.
-- Window mutation (resize, close, focus). Window *state* is exposed read-only; mutation is low-value and fragile.
-- User-visible notifications posted from scripts. Out by default; reconsiderable if a concrete use case emerges.
-- Custom perspective *creation and editing*. Listing and activation are in scope; programmatic definition of perspective rules is likely not scriptable even in OmniFocus Pro and is marked non-goal pending verification when the perspective-management change is drafted.
-- CI coverage for integration tests. CI runs unit tests only; integration tests are local-developer-only by the nature of requiring a running OmniFocus instance.
-- Transactional semantics across batch operations. OmniFocus does not expose transactions; batch tools return per-item result arrays with partial-success semantics.
-
-## Decisions
-
-### Decision 1: JXA is a thin shim; all domain logic runs inside OmniJS via `evaluateJavascript`.
-
-**Choice:** Every tool invocation spawns `osascript -l JavaScript` running a minimal JXA wrapper whose only job is to call `Application('OmniFocus').evaluateJavascript(snippet)`, catch exceptions, and print one line of JSON to stdout. All domain logic — creating folders, setting project types, constructing repetition rules, reading IDs, walking hierarchies — lives in OmniJS snippets and runs inside the OmniFocus process.
-
-**Rationale:** The capability gap between the scripting dictionary and OmniJS is the *entire* reason the prior server failed to cover critical features. Targeting OmniJS directly is the only path to feature parity with the Omni Automation API. JXA's only value here is as the carrier that reaches `evaluateJavascript`; nothing else in the JXA scripting-dictionary surface is used.
-
-**Alternatives considered:**
-
-- *Pure AppleScript, better escaping.* Rejected: the capability gap is structural; no amount of escaping fixes the missing folder, type, move, ID, and recurrence capabilities.
-- *`omnifocus://` URL automation.* Rejected: URL schemes support a narrow slice of operations (add to inbox, open document, complete task) and provide no return channel for IDs or query results.
-- *OmniFocus plug-in bundles installed into the user's library.* Rejected: requires out-of-band user setup, complicates distribution, and still requires an IPC channel back to the MCP server.
-- *Shortcuts.app automation.* Rejected: similar return-channel and capability limitations, and adds a dependency on Shortcuts being configured.
-
-**Bugs this kills:** "cannot create folders," "cannot create Single Actions list," "cannot move tasks between projects," "no project IDs returned," "cannot set recurrence," "folder name ambiguity" (because paths can be resolved via `flattenedFolders` inside OmniJS rather than scripting-dictionary `whose` clauses).
-
-### Decision 2: Arguments are embedded as JSON literals; no string interpolation anywhere.
-
-**Choice:** Snippet files are static `.js` files containing exactly one placeholder token: `__ARGS__`. At runtime, the TypeScript side constructs the script to execute via `template.replace("__ARGS__", JSON.stringify(args))`. The snippet reads `const args = __ARGS__;` as its first line. No other interpolation of user-supplied data into script source is permitted anywhere in the codebase.
-
-**Rationale:** JSON is a syntactic subset of JavaScript. `JSON.stringify` of any JavaScript value produces a string that is both valid JSON and a valid JavaScript expression literal. Embedding it directly into source is injection-safe for arbitrary strings, including apostrophes, quotes, backslashes, newlines, unicode, and emoji — precisely the inputs that broke the prior server. It also has the useful property that the generated script is a standalone, paste-ready snippet: a developer can hand-edit `__ARGS__` in the template and paste it into OmniFocus's Automation Console to reproduce any operation.
-
-**Alternatives considered:**
-
-- *Passing arguments via environment variables.* Rejected: `evaluateJavascript` runs inside OmniFocus's process, which does not inherit the `osascript` environment. The snippet could not read them.
-- *Writing arguments to a temp file and having the snippet read it.* Rejected: OmniJS has no general filesystem read primitive; `FileWrapper` is attachment-scoped. Adds a cleanup burden and a failure mode.
-- *String-escape templating (Handlebars, Mustache, manual backslash escaping).* Rejected: every escape scheme has edge cases. The JSON-literal approach has none because JSON is closed under JavaScript expression syntax.
-
-**Bugs this kills:** "apostrophes in task/project names break AppleScript string generation," plus the entire class of unicode and escape-sequence bugs that haven't been hit yet but would eventually surface under string concatenation.
-
-### Decision 3: Results flow as exactly one line of JSON on stdout.
-
-**Choice:** Every snippet's last expression is `JSON.stringify({ok: true, data: <result>})` or throws. The JXA shim wraps the `evaluateJavascript` call in try/catch. On success, it prints the returned string verbatim followed by a single newline. On failure, it prints `JSON.stringify({ok: false, error: {name, message, stack}})` followed by a single newline. The TypeScript runtime reads stdout, takes the first JSON-parseable line, and asserts `ok`.
-
-**Rationale:** A strict protocol eliminates ambiguity about whether an operation succeeded. The prior server's "parse error on success" bug was a direct consequence of treating incidental AppleScript output as part of the result payload. With a one-line JSON contract, success and failure are trivially distinguishable and the protocol is easy to test in isolation.
-
-**Alternatives considered:**
-
-- *Multi-line JSON with framing.* Rejected: unnecessary complexity for the single-operation-per-invocation model.
-- *Exit code as the success signal.* Rejected: `osascript` exit codes are unreliable across JXA error modes, and an exit code doesn't carry error details.
-- *Writing results to a temp file.* Rejected: adds a cleanup burden and a filesystem round-trip with no benefit.
-
-**Bugs this kills:** "`remove_item` returns parse error on success even when operation succeeded."
-
-### Decision 4: `id.primaryKey` is the canonical address for every entity; name resolution is a separate, explicit, ambiguity-reporting step.
-
-**Choice:** Every read tool returns `{id, ...}` where `id` is `obj.id.primaryKey`. Every write tool (in this and future changes) accepts `id` as the primary addressing parameter. Name and path resolution is a dedicated `resolve_name` tool that takes `{type, query, scope?}` and returns a list of candidate `{id, name, path, ...}` entries. When more than one candidate matches, the tool returns all of them and the caller must decide; it never silently picks.
-
-**Rationale:** The prior server's duplicate-name and folder-ambiguity bugs are consequences of name-based addressing with silent disambiguation. IDs are stable across sessions within OmniFocus. Making ID the canonical address and forcing callers (including LLMs) to resolve ambiguity explicitly is the only way to produce deterministic behavior in a database where names are user-chosen and frequently collide.
-
-**Alternatives considered:**
-
-- *Name-based addressing with a "pick the first match" default.* Rejected: this is exactly what the prior server did, and it routed to the wrong target.
-- *Path-only addressing.* Rejected: paths are fragile to user renames and still ambiguous when the same path exists under different roots (e.g., the same tag name under different parents).
-- *Auto-disambiguation via fuzzy scoring.* Rejected: silent selection is precisely the failure mode being fixed.
-
-**Open question:** Whether `id.primaryKey` values survive OmniFocus sync across devices and across database rebuilds. This is believed to be true but will be verified during the execution-runtime implementation and documented in the runtime README. If IDs turn out not to survive sync, the contract still holds within a single session; callers re-resolving after a sync event is an acceptable fallback.
-
-**Bugs this kills:** "duplicate project names cause wrong-target routing," "folder name ambiguity — same folder name under different parents routes incorrectly," "no project IDs returned — projects only addressable by name."
-
-### Decision 5: Tool parameters are validated with zod at the TS boundary; enums are strict; no type coercion.
-
-**Choice:** Every MCP tool handler defines its input schema as a zod object. Handlers receive already-parsed, already-validated arguments. Enums like project type are `z.enum(["parallel", "sequential", "singleActions"])`. Batch arrays are `z.array(z.object({...}))` — never strings that look like JSON. Invalid inputs are rejected at the TS boundary with structured error messages before any snippet runs.
-
-**Rationale:** The prior server had `sequential` parameters that arrived as strings and were treated as booleans with broken coercion, and `batch_remove_items` parameters that arrived as serialized JSON strings instead of arrays. These are the bug pattern you get when tool schemas are loose and the handler does ad-hoc type massaging. zod at the boundary makes the schema the contract.
-
-**Alternatives considered:**
-
-- *Ad-hoc `typeof` checks in handlers.* Rejected: this is what produced the original bugs.
-- *JSON Schema validation via ajv.* Considered and deferred: zod is TypeScript-native, produces better type inference, and integrates naturally with the MCP SDK's expected schema surface. ajv is fine but adds a second schema language.
-
-**Bugs this kills:** "`sequential` parameter must be a true boolean, not string," "`batch_remove_items` items parameter must be a JSON array, not serialized string."
-
-### Decision 6: Integration tests scope all fixtures under a disposable folder and refuse to run under sync by default.
-
-**Choice:** Every integration test run generates a UUID and creates a top-level folder named `__MCP_TEST_<uuid>__` in the user's OmniFocus database. All fixture projects, folders, tasks, and tags are created inside it. Teardown deletes the folder and everything under it. A preflight check inspects the database's sync configuration and refuses to run if sync is enabled, unless `MCP_TEST_ALLOW_SYNC=1` is set in the environment. Integration tests run serially (OmniFocus is a singleton). CI runs unit tests only.
-
-**Rationale:** Integration tests against a real OmniFocus instance are the only way to validate the OmniJS API contract — mocks would drift. But real-database testing has a failure mode where fixtures leak into the user's actual workflow or, worse, sync to other devices. Fixture-folder scoping contains the blast radius; the sync preflight prevents cross-device leakage by default with an explicit opt-out for users who understand the tradeoff.
-
-**Alternatives considered:**
-
-- *Mocking the OmniJS API.* Rejected: this is the path to building something that passes tests and fails in production.
-- *Dedicated test OmniFocus document.* Rejected: OmniFocus does not support multiple documents in a way that's ergonomic for automated switching.
-- *Snapshot-and-restore the database.* Rejected: there is no supported API for this; copying the sqlite file behind OmniFocus's back is unsafe.
-
-## Risks / Trade-offs
-
-- **Risk:** `id.primaryKey` may not survive OmniFocus sync or database rebuilds. → **Mitigation:** Verify during runtime implementation and document findings. If IDs don't survive sync, document the session-scope guarantee and update `resolve_name` guidance accordingly. This is an open question, not a blocker.
-
-- **Risk:** `evaluateJavascript` may have undocumented size limits on the script argument. → **Mitigation:** Keep snippets small and focused (one operation per file). For batch operations (future change), the snippet iterates over an args array; it does not inline per-item code.
-
-- **Risk:** OmniJS error messages inside `evaluateJavascript` may be lossy when surfaced through JXA. → **Mitigation:** The snippet catches its own errors and constructs the error envelope itself before returning, so error details never cross the OmniJS→JXA boundary as a raw exception.
-
-- **Risk:** Integration tests running against a real OmniFocus instance can still pollute the user's data if teardown fails mid-run. → **Mitigation:** Fixture folders are prefixed with `__MCP_TEST_` and include a UUID; a `clean-test-fixtures` dev script scans for and removes any stragglers. README documents the manual cleanup command.
-
-- **Risk:** OmniFocus sync conflicts from concurrent modifications during a test run. → **Mitigation:** Serial test execution plus the sync preflight. Under the opt-in sync-allowed mode, users accept the risk explicitly.
-
-- **Trade-off:** The MCP server is macOS-only. This is an inherent property of Omni Automation and not negotiable without abandoning the capability goals.
-
-- **Trade-off:** Every tool invocation spawns an `osascript` process, which has startup cost. For single operations this is fine; for high-frequency batch operations it would be noticeable. Batch tools (future change) will therefore execute as a single snippet that iterates internally, not as a loop of tool calls from the caller side.
-
-- **Trade-off:** Snippet files live outside the TypeScript compilation unit. Refactoring a shared OmniJS helper means editing `.js` files that tsc doesn't type-check. Accepted because testability-by-paste is more valuable than type-checking across the boundary; the JS side is small and exercised by integration tests.
-
-## Bug-to-decision traceability
-
-Every documented failure mode of the prior server is mapped to the decision that eliminates it, so the rationale survives archival:
-
-| Prior-server bug | Killed by |
-|---|---|
-| Cannot create folders | Decision 1 (OmniJS exposes `new Folder`) |
-| Cannot create Single Actions list | Decision 1 (OmniJS exposes `containsSingletonActions`) |
-| Cannot move tasks between projects | Decision 1 (OmniJS exposes `moveTasks`) |
-| No project IDs returned | Decisions 1 + 4 (`id.primaryKey` exists in OmniJS and is the canonical address) |
-| Cannot set recurrence/repeat | Decision 1 (OmniJS exposes `Task.RepetitionRule`) |
-| Apostrophes break script generation | Decision 2 (JSON-literal argument embedding) |
-| Duplicate project names cause wrong-target routing | Decision 4 (ID addressing + ambiguity-reporting resolution) |
-| Folder name ambiguity under different parents | Decision 4 (ID addressing + path-based resolution with ambiguity reporting) |
-| `sequential` parameter must be a true boolean, not string | Decision 5 (zod enum validation at TS boundary) |
-| `batch_remove_items` items parameter must be a JSON array | Decision 5 (zod array validation at TS boundary) |
-| `remove_item` returns parse error on success | Decision 3 (strict one-line JSON result protocol) |
-
-## Open Questions
-
-- Do `id.primaryKey` values survive OmniFocus sync across devices and database rebuilds? To be verified during runtime implementation.
-- Does `evaluateJavascript` have a practical size limit on the script argument? To be measured during runtime implementation and documented as an upper bound for future batch snippet design.
-- Does OmniJS expose a reliable way to detect whether sync is enabled without mutating state? Needed for the integration-test preflight check. If not, the preflight falls back to reading the user's OmniFocus preferences via JXA before entering the OmniJS bridge.

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

@@ -1,49 +0,0 @@
-## Why
-
-OmniFocus needs an MCP server that exposes the full Omni Automation JavaScript API to LLM callers. A prior AppleScript-string-generating server exists but has structural limitations: it cannot create folders, cannot create Single Actions lists, cannot move tasks between projects, cannot set recurrence rules, returns no stable IDs, breaks on apostrophes in names, silently routes to the wrong target on duplicate names, and mis-parses successful results as errors. These are not bugs to patch — they are consequences of generating AppleScript source as concatenated strings against a scripting dictionary that lacks the needed capabilities.
-
-This change starts from a clean slate with an architecture that kills those bug classes by construction: all operations execute inside OmniFocus's OmniJS runtime (where the modern API lives) via a JXA bridge, arguments are embedded as JSON literals (never concatenated), identity is always `id.primaryKey`, and results flow as a strict one-line JSON protocol. This first change establishes the runtime foundation and names every capability that will eventually exist, so subsequent changes can fill in the API surface incrementally without re-litigating the architecture.
-
-## What Changes
-
-- Establish a TypeScript MCP server scaffold (`@modelcontextprotocol/sdk`, zod for schemas, vitest for tests) with `src/runtime/`, `src/snippets/`, `src/tools/`, `src/schemas/`, `src/server.ts`, `test/unit/`, `test/integration/`, `package.json`, `tsconfig.json`.
-- Implement the execution runtime: a JXA shim that calls `Application('OmniFocus').evaluateJavascript(snippet)`, wraps results in a strict `{ok, data} | {ok: false, error}` envelope, and prints exactly one line of JSON to stdout.
-- Implement the snippet-authoring convention: static `.js` files with a single `__ARGS__` placeholder, injected by `template.replace("__ARGS__", JSON.stringify(args))`. No other interpolation is permitted anywhere in the codebase.
-- Implement the identity model: every read returns `id.primaryKey`; every write will accept `id` as the canonical address. Name/path resolution is a separate `resolve_name` tool that returns candidate lists on ambiguity and never silently picks a winner.
-- Deliver the minimum-viable read surface needed to prove the bridge end-to-end: `list_projects`, `get_project`, `list_folders`, `get_folder`, `list_tasks`, `get_task`, `list_tags`, `get_tag`, `resolve_name`. No mutating tools in this change.
-- Establish the integration-test harness against a real OmniFocus instance, with all fixtures scoped under a disposable `__MCP_TEST_<uuid>__` top-level folder and a preflight that refuses to run when OmniFocus sync is enabled (unless `MCP_TEST_ALLOW_SYNC=1`).
-- Name every target capability as a stub spec so future changes have a landing place: `recurrence`, `perspective-management`, `window-state`, `forecast`, `database-inspection`, `batch-operations`, `attachments`, `url-automation`, `settings`. Stubs declare scope and non-goals without specifying requirements that later changes will own.
-- Document explicit non-goals: interactive UI APIs (`Form`, `Alert`, `FilePicker`, `FileSaver`), `Speech`, `Device`, clipboard mutation, window mutation, notifications, and custom perspective creation/editing. These are recorded as non-goals in design.md so they don't look like oversights.
-
-## Capabilities
-
-### New Capabilities
-
-- `execution-runtime`: The JXA→OmniJS bridge, snippet loader, argument-injection rule, one-line JSON result protocol, and error model. Fully specified in this change.
-- `identity-resolution`: `id.primaryKey` addressing, name/path resolution with ambiguity reporting, and the `resolve_name` tool contract. Fully specified in this change.
-- `task-management`: Task read operations (`list_tasks`, `get_task`) specified in this change; full CRUD, move, completion, and hierarchy operations land in the `core-crud` change.
-- `project-management`: Project read operations (`list_projects`, `get_project`) specified in this change; CRUD, type (parallel/sequential/singleActions), status, and review metadata land in `core-crud`.
-- `folder-management`: Folder read operations (`list_folders`, `get_folder`) specified in this change; CRUD, nesting, rename, and move land in `core-crud`.
-- `tag-management`: Tag read operations (`list_tags`, `get_tag`) specified in this change; CRUD, nesting, assignment, and status land in `core-crud`.
-- `recurrence`: Stub naming the capability for Task.RepetitionRule construction, RepetitionMethod, structured schema plus raw RRULE escape hatch, and clearing recurrence. Requirements land in the `recurrence` change.
-- `perspective-management`: Stub naming the capability for listing built-in and custom perspectives, activating a perspective in a window, and reading perspective details. Custom perspective creation/editing is a non-goal pending API verification.
-- `window-state`: Stub naming the capability for read-only window state (current window, active perspective, sidebar selection, content selection). Window mutation is a non-goal.
-- `forecast`: Stub naming the capability for forecast days, tasks due/deferred on a day, and forecast metadata.
-- `database-inspection`: Stub naming the capability for scoped, paged, filtered database traversal including `dump_database`, inbox contents, and database metadata.
-- `batch-operations`: Stub naming the capability for batch variants of mutating tools with per-item result arrays and partial-success semantics.
-- `attachments`: Stub naming the capability for `FileWrapper`-based attachment listing and round-trip on task notes.
-- `url-automation`: Stub naming the capability for `omnifocus://` URL construction and parsing.
-- `settings`: Stub naming the capability for reading app settings and preferences where exposed.
-
-### Modified Capabilities
-
-None. This is a clean-slate project with no prior specs.
-
-## Impact
-
-- **New repository structure** with TypeScript toolchain, MCP SDK, zod, vitest.
-- **Runtime dependency on macOS** (`osascript`) and a running OmniFocus instance. The server is macOS-only by nature of the Omni Automation platform.
-- **Integration tests mutate a real OmniFocus database.** Mitigated by fixture-folder scoping and a sync-enabled preflight check. Documented loudly in the README.
-- **No CI coverage for integration tests.** CI runs unit tests only (snippet injection, zod schema validation, result-protocol parsing). Integration is local-developer-only.
-- **Replaces a prior AppleScript-based MCP server.** Callers migrating from the old server will encounter breaking changes in tool names, parameter types, and result shapes. This is accepted because the prior server's contract was structurally broken; compatibility is not a goal.
-- **No external network dependencies.** The server runs entirely locally against the user's OmniFocus database.

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

@@ -1,9 +0,0 @@
-## ADDED Requirements
-
-### Requirement: Capability declared
-
-The `attachments` capability SHALL cover listing, reading, adding, and removing file attachments on task notes via the OmniJS `FileWrapper` API. The on-wire representation of attachment contents across the MCP boundary (inline base64, filesystem path reference, or a hybrid with a size threshold) SHALL be decided when the `attachments` 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 attachment tools
-- **THEN** it lands requirements under this capability and makes the on-wire encoding decision explicit

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

@@ -1,9 +0,0 @@
-## ADDED Requirements
-
-### Requirement: Capability declared
-
-The `batch-operations` capability SHALL cover batch variants of every mutating tool (create, update, delete, move, complete, assign). Batch tools SHALL accept strictly typed arrays validated at the TypeScript boundary (never serialized JSON strings) and SHALL return a per-item result array with partial-success semantics: each element is an `{ok, data?, error?}` envelope carrying that item's outcome independent of other items. Batch tools SHALL execute as a single OmniJS snippet that iterates internally, not as a loop of per-item bridge invocations. Requirements for individual batch tools SHALL be added by the `batch-operations` change.
-
-#### Scenario: Capability is named and semantics are fixed
-- **WHEN** a future change proposes adding batch tools
-- **THEN** it lands requirements under this capability with typed-array validation and partial-success result semantics as invariants

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

@@ -1,9 +0,0 @@
-## ADDED Requirements
-
-### Requirement: Capability declared
-
-The `database-inspection` capability SHALL cover scoped, paged, and filtered traversal of the full OmniFocus database, including a `dump_database` tool that accepts `{scope, id?, include, format}` parameters, inbox inspection, and database metadata (name, sync status, object counts). The default behavior of `dump_database` SHALL exclude completed tasks, dropped entities, and task notes to keep payloads manageable; those are opt-in via the `include` parameter. 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 database-inspection tools
-- **THEN** it lands requirements under this capability rather than inventing a new capability name