neotoma 0.3.0 → 0.3.2

package/.cursor/plans/error_reporting_command_8868f27b.plan.md

@@ -1,255 +0,0 @@
----
-name: Error Reporting Command
-overview: Create a Cursor command that allows agents to report errors for resolution via Cursor Cloud Agent. The command will collect structured error information and store it in a format that Cursor Cloud Agent can discover and process.
-todos: []
----
-
-# Error Reporting Command
-
-Create a Cursor command that enables agents to report errors for automated resolution by Cursor Cloud Agent.
-
-## Files to Create/Modify
-
-1. **`.cursor/commands/report_error.md`** - Main command documentation
-2. **`.cursor/commands.json`** - Register the new command
-3. **`foundation-config.yaml`** (optional) - Add configuration for error reporting
-
-## Command Structure
-
-### Command Name
-
-`report_error` or `report-error`
-
-### Command Location
-
-- Source: `foundation/agent_instructions/cursor_commands/report_error.md`
-- Symlink: `.cursor/commands/report_error.md` (via setup_symlinks)
-
-## Workflow
-
-1. **Error Detection & Collection**
-
-- Extract error message and stack trace from context
-- Identify affected files/modules from error paths
-- Capture agent context (agent_id, task being performed)
-- Determine error category (build, runtime, test, dependency, etc.)
-
-2. **Error Classification**
-
-- **Build Error**: TypeScript compilation, module resolution, missing dependencies
-- **Runtime Error**: MCP server errors, API failures, database errors
-- **Test Error**: Test failures, assertion errors
-- **Dependency Error**: Missing modules, version conflicts
-- **Configuration Error**: Missing env vars, invalid config
-
-3. **Generate Error Report**
-
-- Create structured error report with:
-    - Error ID (UUID or timestamp-based)
-    - Error category
-    - Error message (sanitized, no PII)
-    - Stack trace (truncated if too long)
-    - Affected files/modules
-    - Agent context
-    - Timestamp
-    - Severity (critical, high, medium, low)
-
-4. **Store Error Report**
-
-- Save to `.cursor/error_reports/` directory
-- Filename format: `error_[timestamp]_[category].json`
-- Also create human-readable markdown summary: `error_[timestamp]_[category].md`
-
-5. **Notify/Queue for Resolution**
-
-- Create or append to `.cursor/error_reports/pending.json` (queue file)
-- Format suitable for Cursor Cloud Agent consumption
-- Include priority/severity for processing order
-
-6. **Output Summary**
-
-- Present error report summary to user
-- Show error ID and location
-- Indicate if error was queued for resolution
-
-## Error Report Schema
-
-```json
-{
-  "error_id": "uuid-v7",
-  "timestamp": "ISO-8601",
-  "category": "build|runtime|test|dependency|configuration",
-  "severity": "critical|high|medium|low",
-  "error_message": "sanitized error message",
-  "stack_trace": "truncated stack trace",
-  "affected_files": ["path/to/file1.ts", "path/to/file2.ts"],
-  "affected_modules": ["module_name"],
-  "agent_context": {
-    "agent_id": "cursor-agent",
-    "task": "description of task",
-    "command": "command_name if applicable"
-  },
-  "environment": {
-    "node_version": "v20.x.x",
-    "os": "darwin|linux|windows",
-    "neotoma_env": "development|production"
-  },
-  "resolution_status": "pending|in_progress|resolved|failed",
-  "resolution_notes": ""
-}
-```
-
-
-
-## Integration Points
-
-### With Cursor Cloud Agent
-
-- Cursor Cloud Agent monitors `.cursor/error_reports/pending.json`
-- Processes errors in priority order (critical → low)
-- Updates `resolution_status` when working on error
-- Moves resolved errors to `.cursor/error_reports/resolved/`
-
-### With Existing Bug Fix Workflow
-
-- Can trigger existing `fix_feature_bug` command if error is classified as bug
-- Option to auto-classify certain error types as bugs
-
-## Command Usage
-
-### Explicit Invocation
-
-```javascript
-/report_error
-```
-
-Agent prompts for error details if not in context.
-
-### Automatic Detection
-
-- Detect error patterns in agent output
-- Auto-trigger when MCP errors occur
-- Auto-trigger on build failures
-
-## Configuration
-
-Add to `foundation-config.yaml`:
-
-```yaml
-development:
-  error_reporting:
-    enabled: true
-    auto_detect: true
-    auto_classify_bugs: true
-    severity_threshold: "medium"  # Only report medium and above
-    max_stack_trace_length: 5000
-    retention_days: 30
-    output_directory: ".cursor/error_reports"
-```
-
-
-
-## File Structure
-
-```javascript
-.cursor/
-  error_reports/
-    pending.json          # Queue of errors awaiting resolution
-    error_[timestamp]_[category].json  # Individual error reports
-    error_[timestamp]_[category].md    # Human-readable summaries
-    resolved/            # Resolved errors (archived)
-      error_[timestamp]_[category].json
-```
-
-
-
-## Implementation Details
-
-### Error Detection Patterns
-
-- MCP error responses (e.g., "MCP error -32603")
-- Build errors (TypeScript compilation failures)
-- Module resolution errors (e.g., "Cannot find module")
-- Runtime exceptions in agent output
-
-### Sanitization Rules
-
-- Remove PII from error messages
-- Truncate stack traces to max length
-- Remove sensitive paths (replace with placeholders)
-- Redact API keys, tokens, credentials
-
-### Priority Calculation
-
-- **Critical**: Server crashes, data loss, security issues
-- **High**: Feature breakage, blocking errors
-- **Medium**: Non-blocking errors, warnings
-- **Low**: Cosmetic issues, deprecation warnings
-
-## Example Error Report
-
-**JSON** (`.cursor/error_reports/error_20250127_143022_build.json`):
-
-```json
-{
-  "error_id": "01JQZ8X9K2M3N4P5Q6R7S8T9U0",
-  "timestamp": "2025-01-27T14:30:22Z",
-  "category": "build",
-  "severity": "high",
-  "error_message": "Cannot find module '../db'",
-  "stack_trace": "Error: Cannot find module '../db'\n  at ...",
-  "affected_files": [
-    "src/services/raw_storage.ts",
-    "src/services/interpretation.ts",
-    "src/services/entity_queries.ts"
-  ],
-  "affected_modules": ["db"],
-  "agent_context": {
-    "agent_id": "cursor-agent",
-    "task": "Transfer contacts from Parquet to Neotoma",
-    "command": null
-  },
-  "environment": {
-    "node_version": "v20.11.0",
-    "os": "darwin",
-    "neotoma_env": "development"
-  },
-  "resolution_status": "pending",
-  "resolution_notes": ""
-}
-```
-
-**Markdown** (`.cursor/error_reports/error_20250127_143022_build.md`):
-
-```markdown
-# Error Report: Build Error
-
-**Error ID:** `01JQZ8X9K2M3N4P5Q6R7S8T9U0`  
-**Timestamp:** 2025-01-27T14:30:22Z  
-**Category:** build  
-**Severity:** high  
-**Status:** pending
-
-## Error Message
-Cannot find module '../db'
-
-## Affected Files
-- `src/services/raw_storage.ts`
-- `src/services/interpretation.ts`
-- `src/services/entity_queries.ts`
-
-## Context
-Agent was transferring contacts from Parquet to Neotoma when this build error occurred.
-
-## Resolution
-Awaiting resolution by Cursor Cloud Agent.
-```
-
-
-
-## Related Commands
-
-- `fix_feature_bug` - Can be triggered from error report if classified as bug
-- `analyze` - Could analyze error patterns across reports
-
-## Testing

package/.cursor/plans/mcp-cli-action-item-01-openapi-core.plan.md

@@ -1,30 +0,0 @@
----
-name: ""
-overview: ""
-todos: []
-isProject: false
----
-
-# Action item 1 plan: contract authority
-
-## Context summary
-
-OpenAPI lives in `openapi.yaml`. MCP tool schemas live in `src/server.ts` and `docs/specs/MCP_SPEC.md`. The report calls for a single contract source of truth.
-
-## Key problems solved
-
-- MCP tool schemas can drift from OpenAPI.
-- Contract authority is split across code and docs.
-
-## Key solutions implemented
-
-- Select a single contract source of truth.
-- Generate secondary artifacts from that source.
-
-## Plan
-
-1. Decide contract authority direction. Use OpenAPI as the source or use MCP schemas as the source.
-2. Define a generator pipeline. Generate MCP tool schemas or generate OpenAPI from MCP schemas.
-3. Update `src/server.ts` to use the generated tool schemas instead of hand-written schemas.
-4. Update `docs/specs/MCP_SPEC.md` to be generated from the same source or to reference the generated output.
-5. Add drift tests that compare MCP tool schemas, OpenAPI, and docs for parity.

package/.cursor/plans/mcp-cli-action-item-02-openapi-mcp-cli-mapping.plan.md

@@ -1,18 +0,0 @@
-# Action item 2 plan: enforce 1 to 1 mapping
-
-## Context summary
-`src/shared/contract_mappings.ts` maps OpenAPI operations. MCP only tools bypass mapping. The report requires 1 to 1 coverage between OpenAPI operations and MCP tools or CLI commands.
-
-## Key problems solved
-- MCP only tools have no contract mapping.
-- Parity tests do not cover all MCP tools.
-
-## Key solutions implemented
-- Require every MCP tool to map to an OpenAPI operation or CLI command.
-- Add parity tests that enforce coverage.
-
-## Plan
-1. Inventory MCP tools in `src/server.ts`. Classify each tool as OpenAPI mapped, CLI mapped, or MCP only.
-2. For each MCP only tool, add an OpenAPI operation or a CLI command that maps to it.
-3. Update `src/shared/contract_mappings.ts` with all new mappings.
-4. Expand contract mapping tests in `tests/contract/` to fail on unmapped MCP tools.

package/.cursor/plans/mcp-cli-action-item-03-cli-equivalent-logging.plan.md

@@ -1,18 +0,0 @@
-# Action item 3 plan: log CLI equivalents for MCP
-
-## Context summary
-`buildCliEquivalentInvocation()` logs CLI commands for MCP tool calls, but MCP only tools log placeholders.
-
-## Key problems solved
-- CLI equivalent logs are incomplete.
-- MCP only tools have no real command reference.
-
-## Key solutions implemented
-- Define CLI equivalents for every MCP tool.
-- Log real commands for all MCP tool calls.
-
-## Plan
-1. Enumerate MCP only tools and define intended CLI commands for each.
-2. Add CLI implementations or wrappers that call the same service layer as MCP.
-3. Update `buildCliEquivalentInvocation()` to return a real command for every tool.
-4. Add tests that fail if any CLI equivalent is a placeholder.

package/.cursor/plans/mcp-cli-action-item-06-error-taxonomy.plan.md

@@ -1,18 +0,0 @@
-# Action item 6 plan: strict error taxonomy
-
-## Context summary
-REST handlers return string errors. Error responses are not aligned to `docs/subsystems/errors.md`.
-
-## Key problems solved
-- Error responses are not machine checkable.
-- Canonical error codes are not enforced.
-
-## Key solutions implemented
-- Use ErrorEnvelope for REST and MCP responses.
-- Enforce canonical error codes in handlers.
-
-## Plan
-1. Introduce a shared error factory that emits ErrorEnvelope with canonical codes.
-2. Replace string errors in `src/actions.ts` with ErrorEnvelope responses.
-3. Align MCP error handling in `src/server.ts` with the same error factory.
-4. Add tests that assert `error_code`, `message`, and `timestamp` fields.

package/.cursor/plans/mcp-cli-action-item-07-fixture-replay-graphs.plan.md

@@ -1,18 +0,0 @@
-# Action item 7 plan: replayable fixtures with expected graphs
-
-## Context summary
-Fixtures are in `tests/fixtures/`, but expected extracted graph outputs are not centralized or enforced.
-
-## Key problems solved
-- Deterministic replay lacks a reference output.
-- Fixtures do not include graph expectations.
-
-## Key solutions implemented
-- Store expected graph outputs alongside fixtures.
-- Add replay tests that compare reducer output to expected graphs.
-
-## Plan
-1. Define an expected output format for snapshots and relationships.
-2. Add expected outputs for a starter set of fixtures in `tests/fixtures/`.
-3. Add replay tests that load fixtures and compare output to expected graphs.
-4. Update fixture documentation to describe the expected output format.

package/.cursor/plans/mcp-cli-action-item-08-cli-reference-executor.plan.md

@@ -1,18 +0,0 @@
-# Action item 8 plan: CLI as reference executor
-
-## Context summary
-MCP and REST are the primary execution paths. There is no CLI wrapper that uses the same service layer as the reference executor.
-
-## Key problems solved
-- Execution logic is duplicated across MCP and REST.
-- CLI is not a reference path for fidelity checks.
-
-## Key solutions implemented
-- Add a CLI module that calls the same service layer as MCP and REST.
-- Use CLI outputs as the reference for parity and replay tests.
-
-## Plan
-1. Identify shared service entry points used by MCP and REST.
-2. Create CLI commands that call those service entry points directly.
-3. Refactor MCP and REST to share that service layer where needed.
-4. Add tests that compare CLI and MCP outputs for the same inputs.

package/.cursor/plans/mcp-cli-action-item-09-mcp-tools-atomic.plan.md

@@ -1,18 +0,0 @@
-# Action item 9 plan: keep MCP tools boring and atomic
-
-## Context summary
-MCP tools live in `src/server.ts`. Test failures show method name mismatches. Tool naming and boundaries need stabilization.
-
-## Key problems solved
-- Tool name instability breaks tests and clients.
-- Tool boundaries are not enforced as atomic actions.
-
-## Key solutions implemented
-- Enforce stable naming and versioning rules.
-- Add tests for tool name stability and atomic behavior.
-
-## Plan
-1. Define tool naming and versioning rules in docs and code.
-2. Add a registry validation test that asserts stable tool names.
-3. Split composite tools into atomic operations where needed.
-4. Update docs that reference tool names to the canonical set.

package/.cursor/plans/mcp-cli-action-item-10-canonical-walkthrough.plan.md

@@ -1,18 +0,0 @@
-# Action item 10 plan: canonical ingest to replay walkthrough
-
-## Context summary
-The pipeline is documented across multiple files, but there is no standalone walkthrough that ties ingest, normalize, extract, query, and replay into one guide.
-
-## Key problems solved
-- Users lack a single end to end walkthrough.
-- Ingestion and replay steps are scattered across docs.
-
-## Key solutions implemented
-- Create a standalone walkthrough doc.
-- Include deterministic examples with expected outputs.
-
-## Plan
-1. Create a new walkthrough doc under `docs/` that covers ingest, normalize, extract, query, and replay.
-2. Include CLI and MCP examples with deterministic inputs and outputs.
-3. Link to subsystem docs for implementation details.
-4. Add the new doc to `docs/context/index_rules.mdc` and `docs/doc_dependencies.yaml`.

package/.cursor/plans/mcp-cli-action-item-11-fixtures-expected-outputs.plan.md

@@ -1,18 +0,0 @@
-# Action item 11 plan: fixtures repository with expected outputs
-
-## Context summary
-Fixtures are in `tests/fixtures/`, but expected outputs are not centrally published or enforced.
-
-## Key problems solved
-- Fixture outputs are not discoverable or consistent.
-- Replay tests lack a canonical output target.
-
-## Key solutions implemented
-- Add expected outputs alongside fixtures in a consistent layout.
-- Document the expected output format and update cadence.
-
-## Plan
-1. Define a folder structure for expected outputs under `tests/fixtures/`.
-2. Add expected outputs for key fixture types.
-3. Add validation tooling that fails if expected outputs are missing.
-4. Update fixture documentation to reference expected outputs.

package/.cursor/plans/mcp-cli-action-item-12-failure-gallery.plan.md

@@ -1,18 +0,0 @@
-# Action item 12 plan: determinism failure gallery
-
-## Context summary
-Failure analyses exist in `docs/reports/`, but there is no curated failure gallery that groups determinism break cases and system responses.
-
-## Key problems solved
-- Determinism failures are scattered across reports.
-- There is no single summary of failure modes and responses.
-
-## Key solutions implemented
-- Create a failure gallery index doc.
-- Link each failure mode to existing analyses and tests.
-
-## Plan
-1. Create a new report doc under `docs/reports/` that lists determinism failure modes.
-2. Group failure modes by subsystem and include remediation steps.
-3. Link each entry to existing reports and test references.
-4. Add the new report to `docs/context/index_rules.mdc` and `docs/doc_dependencies.yaml`.

package/.cursor/plans/mcp_source-path_documentation_5ce48609.plan.md

@@ -1,83 +0,0 @@
----
-name: MCP source-path documentation
-overview: Improve MCP instructions and documentation so agents and implementers consistently use the structured path for conversation- or tool-sourced data and the unstructured path for file- or resource-sourced data, with clear source-to-path rules and aligned wording everywhere.
-todos: []
-isProject: false
----
-
-# MCP documentation: conversation- vs file/resource-sourced storage paths
-
-## Goal
-
-Make the **source of the data** (where it came from) the explicit basis for choosing the storage path, and align all MCP-facing text and docs to that rule so agents and readers see one consistent story.
-
-## Current state
-
-- **[MCP_SPEC.md](docs/specs/MCP_SPEC.md)** (sections 2.6 and 3.1): Decision logic is input-shaped ("Raw file content?" / "Structured source?") and filename guidance mentions "data from chat or another MCP, not from a file" but does not frame a single "source → path" rule.
-- **[instructions.md](docs/developer/mcp/instructions.md)**: Tells agents to store from "conversational contexts" and "from chat or other MCPs (not from a file)" and to omit `original_filename` in that case; does not state "use structured path for conversation/tool-sourced, unstructured for file/resource-sourced."
-- **[tool_descriptions.yaml](docs/developer/mcp/tool_descriptions.yaml)**: Describes `store` / `store_structured` / `store_unstructured` by input shape (entities vs file), not by source of data.
-- **[mcp_overview.md](docs/developer/mcp_overview.md)**: Only shows a structured-store example; no guidance on when to use file vs entities or on source types.
-
-## Recommended changes
-
-### 1. Add a canonical "source → path" rule in MCP_SPEC
-
-**File:** [docs/specs/MCP_SPEC.md](docs/specs/MCP_SPEC.md)
-
-- In **section 2.6** ("Using the Unified `store` Action"), add a short **"Choosing the storage path by source"** subsection **before** the existing "For Unstructured Source" / "For Structured Source" blocks.
-- State the rule explicitly:
-  - **Conversation-sourced or tool-sourced:** Data from what the user said in chat, or from another MCP/tool (e.g. email, calendar) where the agent is extracting entities. Use the **structured** path: `store` or `store_structured` with an `entities` array. Omit `original_filename`.
-  - **File-sourced or resource-sourced:** User attached a file, or the agent has a file/blob to preserve as an artifact (eime_type or `file_path`). Use the **unstructured** path: `store` or `store_unstructured` with `file_content`+`mime_type` or `file_path`. Do not interpret the file; pass it raw so the server can store and optionally interpret.
-- Add one sentence of rationale: choosing by source keeps provenance correct (artifact vs agent-derived) and avoids double interpretation of files.
-- **Reframe the existing "Decision Logic"** (currently two bullets around lines 297–299) to use this source framing, e.g.:
-  - "**File- or resource-sourced** (user attachment or a file/blob to preserve) → use `store` with `file_content`+`mime_type` or `file_path`."
-  - "**Conversation- or tool-sourced** (what the user said or structured data from another MCP) → use `store` with `entities`. Omit `original_filename`."
-- Keep all existing schema and parameter details; only add the subsection and adjust the decision bullets.
-
-### 2. Add the same rule to MCP server instructions
-
-**File:** [docs/developer/mcp/instructions.md](docs/developer/mcp/instructions.md)
-
-- Inside the instruction block (the fenced block that the server sends to clients), add one or two lines that agents see at runtime:
-  - Use the **structured** path (store with `entities`) for data from **conversation** or from **other MCPs** (e.g. email, calendar) when you are extracting and storing entities; omit `original_filename`.
-  - Use the **unstructured** path (store with `file_content`+`mime_type` or `file_path`) when the user **attached a file** or you have a **file/resource to preserve**; pass the raw file and do not interpret it yourself.
-- Place these near the existing line "When storing structured data from chat or other MCPs (not from a file), omit original_filename" so the rule is co-located with the filename rule (e.g. immediately before or after it). Optionally fold that line into the new "structured path" line to avoid repetition.
-
-### 3. Align tool descriptions with source framing
-
-**File:** [docs/developer/mcp/tool_descriptions.yaml](docs/developer/mcp/tool_descriptions.yaml)
-
-- **store:** Prepend a single sentence to the existing description: e.g. "Choose path by source: file- or resource-sourced (attachment/file to preserve) → use file_content+ mime_type or file_path; conversation- or tool-sourced (chat or other MCP) → use entities." Then keep the rest of the current store description unchanged.
-- **store_structured:** Change to something like: "Store structured entities only. Use for **conversation- or tool-sourced** data (e.g. from chat or another MCP). Use when you already have entity objects and do not need file ingestion."
-- **store_unstructured:** Change to something like: "Store raw files only. Use when data is **file- or resource-sourced** (user attachment or file to preserve). Provide file_content (base64) + mime_type or file_path."
-
-Keep YAML formatting and length constraints so the server still loads the file; shorten if the combined store description exceeds client limits.
-
-### 4. Add a short "When to use which path" note in mcp_overview
-
-**File:** [docs/developer/mcp_overview.md](docs/developer/mcp_overview.md)
-
-- In "What MCP provides" or immediately after the store example, add a brief note:
-  - "**Storing:** Use the **structured** path (store with `entities`) for conversation- or tool-sourced data; use the **unstructured** path (store with `file_content`/`file_path`) for file- or resource-sourced data. See MCP_SPEC section 2.6 for the full rule."
-- Optionally add a second example showing an unstructured-store case (e.g. store with `file_path` and `mime_type`) so both paths are represented.
-
-### 5. Optional: vocabulary entry for source origin
-
-**File:** [docs/vocabulary/canonical_terms.md](docs/vocabulary/canonical_terms.md)
-
-- If you want a single place that defines the terms used in the spec and instructions, add a short note under **Source** (or a small "Source origin" subsection):
-  - **Conversation-sourced:** Data from what the user said in chat or from the agent’s dialogue context; store via the structured path.
-  - **File-sourced / resource-sourced:** Data that is a user-attached file or another artifact (file/blob) to preserve; store via the unstructured path so the server can store the artifact and optionally run interpretation.
-- This is optional; the spec and instructions can be clear without changing the vocabulary, but it helps downstream docs and future edits to reuse the same terms.
-
-## Out of scope
-
-- No changes to server code ([src/server.ts](src/server.ts)) or to request/response schemas.
-- No new MCP actions or parameters.
-- No changes to interpretation behavior or provenance storage; only documentation and instruction text.
-
-## Validation
-
-- After edits: read through [docs/specs/MCP_SPEC.md](docs/specs/MCP_SPEC.md) section 2.6 and [docs/developer/mcp/instructions.md](docs/developer/mcp/instructions.md) and confirm the rule is stated the same way (conversation/tool → structured, file/resource → unstructured).
-- Confirm [docs/developer/mcp/tool_descriptions.yaml](docs/developer/mcp/tool_descriptions.yaml) is valid YAML and that the server still loads instructions and tool descriptions (manual or existing test).
-- If vocabulary is updated, ensure [docs/specs/MCP_SPEC.md](docs/specs/MCP_SPEC.md) and instructions reference the same terms (conversation-sourced, file-sourced, resource-sourced) for consistency.