neotoma 0.3.0 → 0.3.2

package/docs/releases/v0.2.2/execution_schedule.md

@@ -1,123 +0,0 @@
-# Release v0.2.2 — Execution Schedule
-**Release ID**: v0.2.2  
-**Release Name**: list_capabilities MCP Action  
-**Release Type**: Not Marketed  
-**Deployment**: Production (neotoma.io)  
-**Generated**: 2025-12-31
-## Execution Strategy
-- **Type**: Single Feature Unit
-- **Max Parallel FUs**: 1 (single FU release)
-- **Max High-Risk FUs in Parallel**: 1
-## Batch Execution Plan
-#### Batch 0: list_capabilities MCP Action
-**Feature Units:**
-- `FU-304`: MCP Action — `list_capabilities`
-**Dependencies:**
-- FU-200 (MCP Server Core from v0.1.0) — completed in v0.1.0
-**Description:**
-New MCP action for dynamic capability discovery. Enables integrations to programmatically discover available capabilities, their schemas, field requirements, and entity extraction rules. Returns all available capabilities with:
-- Capability ID, intent, version
-- Primary entity type and schema version
-- Canonicalization fields (used for deduplication)
-- Entity extraction rules (which entities are automatically extracted)
-- Example payloads for each capability type
-Supports filtering by intent and version for targeted discovery.
-**Acceptance Criteria:**
-- `list_capabilities` MCP action returns all 5 capabilities with complete metadata
-- Filtering by intent and version works correctly
-- Response structure matches MCP specification
-- Example payloads provided for all 5 capabilities
-- `submit_payload` tool description references `list_capabilities`
-- Response time < 100ms (capability registry is static)
-- No breaking changes to existing MCP actions
-- Backward compatible (existing integrations continue to work)
-**Implementation Tasks:**
-1. Add `list_capabilities` tool definition to MCP server tools array
-2. Add switch case handler for `list_capabilities` in CallToolRequestSchema
-3. Implement `listCapabilities()` private method with filtering logic
-4. Add `generateExamplePayload()` helper method
-5. Enhance `submit_payload` tool description to reference `list_capabilities`
-6. Update `capability_id` and `body` field descriptions with discovery guidance
-7. Update MCP specification documentation with new action
-8. Add integration tests for discovery → submission workflows
-**Estimated Duration**: 4-6 hours
-**Code Changes:**
-- `src/server.ts`: Add tool definition, handler, and implementation
-- `docs/specs/MCP_SPEC.md`: Add `list_capabilities` specification
-- `tests/integration/list_capabilities.test.ts`: Add integration tests (new file)
-**Testing Strategy:**
-- Unit tests: Filtering logic, example payload generation
-- Integration tests: Full discovery → submission workflows
-- Protocol tests: MCP protocol compliance
-- Backward compatibility tests: Existing integrations unaffected
-- Performance tests: Response time < 100ms
-## Checkpoint 1: Pre-Release Sign-Off
-**After Batch 0 Completion:**
-**Validation Steps:**
-1. Review implementation against plan
-2. Verify all acceptance criteria met
-3. Run full integration test suite
-4. Verify backward compatibility
-5. Check MCP specification updated
-6. Validate production readiness
-**Decision Points:**
-- ✅ All tests passing?
-- ✅ MCP specification updated?
-- ✅ Backward compatibility validated?
-- ✅ Response times within target?
-- ✅ Example payloads valid?
-**Sign-Off Required Before:**
-- Deployment to production (neotoma.io)
-- Marking release as `ready_for_deployment`
-## Release Timeline
-**Estimated Timeline:**
-- **Batch 0**: 4-6 hours (implementation + testing)
-- **Checkpoint 1**: 1 hour (validation + sign-off)
-- **Total**: 5-7 hours
-**Critical Path:**
-- FU-304 implementation → integration tests → MCP spec update → sign-off → deployment
-## Risk Assessment
-**Risk Level**: Low
-**Justification:**
-- Single FU release (isolated scope)
-- Additive feature (no breaking changes)
-- Uses existing capability registry (no new infrastructure)
-- No database changes required
-- No UI changes (MCP-only)
-- Backward compatible (existing integrations continue to work)
-**Mitigation Strategies:**
-- Comprehensive integration tests before deployment
-- Backward compatibility validation with existing tests
-- Response schema validation against specification
-- Example payload validation against capability schemas
-## Dependencies
-**External Dependencies:**
-- FU-200 (MCP Server Core from v0.1.0) — ✅ Completed
-**Internal Dependencies:**
-- Existing capability registry (`src/services/capability_registry.ts`) — ✅ Available
-- Existing `listCapabilities()` function — ✅ Available
-- MCP protocol infrastructure — ✅ Available
-**No blockers identified.**
-## Post-Execution
-**After Batch 0:**
-1. Run full integration test suite
-2. Validate backward compatibility
-3. Check response times (target: < 100ms)
-4. Verify example payloads
-5. Review MCP specification updates
-6. Complete Checkpoint 1 validation
-**On Success:**
-- Mark release as `ready_for_deployment`
-- Deploy to production (neotoma.io)
-- Mark release as `deployed`
-- Run post-deployment validation
-- Mark release as `completed`
-**On Failure:**
-- Review failure mode (see Pre-Mortem in manifest.yaml)
-- Apply mitigation strategy
-- Re-run affected tests
-- If mitigation fails, rollback per rollback plan
-
-
-
-

package/docs/releases/v0.2.2/integration_tests.md

@@ -1,258 +0,0 @@
-# Release v0.2.2 — Integration Tests
-**Release ID**: v0.2.2  
-**Release Name**: list_capabilities MCP Action  
-**Release Type**: Not Marketed  
-**Deployment**: Production (neotoma.io)
-## Test Execution
-Tests are executed automatically by the release orchestrator after batch completion. Test commands are defined in the `test:` field for each test.
-## Integration Test Catalog
-### IT-001: Capability Discovery → Payload Submission Flow
-**Goal:** Verify that capability discovery enables successful payload submission with complete metadata.
-**Batches Covered:** 0
-**FUs Involved:** FU-304, FU-201 (submit_payload)
-**Test Steps:**
-1. Call `list_capabilities` via MCP with no filters
-2. Verify response structure matches specification:
-   - Contains `capabilities` array
-   - Contains `total` count
-3. Verify all 5 capabilities returned:
-   - `neotoma:store_invoice:v1`
-   - `neotoma:store_transaction:v1`
-   - `neotoma:store_receipt:v1`
-   - `neotoma:store_contract:v1`
-   - `neotoma:store_note:v1`
-4. For each capability, verify complete metadata:
-   - `id`, `intent`, `version` present
-   - `primary_entity_type`, `schema_version` present
-   - `canonicalization_fields` array populated
-   - `entity_extraction` array populated with extraction rules
-   - `example_payload` object present and non-empty
-5. Select invoice capability from response
-6. Use returned `capability_id` to submit payload via `submit_payload`
-7. Use `example_payload` structure as guide for payload body
-8. Verify payload submission succeeds
-9. Verify entities extracted according to capability's `entity_extraction` rules
-**Expected Results:**
-- `list_capabilities` returns all 5 capabilities
-- Each capability has complete metadata
-- Example payloads are valid and non-empty
-- `submit_payload` succeeds using discovered capability_id
-- Entities extracted match capability extraction rules
-**Machine-Checkable:**
-```bash
-test: "tests/integration/list_capabilities_to_submission.test.ts"
-```
-**Status:** ⏳ not_run
-### IT-002: Filtered Discovery → Payload Submission Flow
-**Goal:** Verify that capability filtering works correctly and enables targeted payload submission.
-**Batches Covered:** 0
-**FUs Involved:** FU-304, FU-201 (submit_payload)
-**Test Steps:**
-1. Call `list_capabilities` with filter `{ intent: "store_invoice" }`
-2. Verify only invoice capabilities returned (should be 1 capability)
-3. Verify returned capability has `intent: "store_invoice"`
-4. Verify `total` count equals 1
-5. Call `list_capabilities` with filter `{ version: "v1" }`
-6. Verify all v1 capabilities returned (should be all 5)
-7. Verify all returned capabilities have `version: "v1"`
-8. Call `list_capabilities` with filter `{ intent: "store_invoice", version: "v1" }`
-9. Verify only `neotoma:store_invoice:v1` returned
-10. Use discovered capability to submit invoice payload via `submit_payload`
-11. Verify submission succeeds
-**Expected Results:**
-- Filtering by intent returns only matching capabilities
-- Filtering by version returns only matching capabilities
-- Combined filters work correctly (AND logic)
-- Filtered capabilities can be used for payload submission
-- `total` count matches filtered results
-**Machine-Checkable:**
-```bash
-test: "tests/integration/list_capabilities_filtering.test.ts"
-```
-**Status:** ⏳ not_run
-### IT-003: Tool Description Guidance Flow
-**Goal:** Verify that enhanced tool descriptions guide integrations to use capability discovery.
-**Batches Covered:** 0
-**FUs Involved:** FU-304, FU-201 (submit_payload)
-**Test Steps:**
-1. Query MCP `ListTools` to get all tool definitions
-2. Locate `list_capabilities` tool definition
-3. Verify `list_capabilities` description:
-   - Explains purpose (dynamic capability discovery)
-   - Mentions schemas, field requirements, entity extraction rules
-   - Explains usage for discovering data types
-4. Locate `submit_payload` tool definition
-5. Verify `submit_payload` description:
-   - References `list_capabilities` for discovery
-   - Mentions common capability IDs
-   - Guides users to use discovery before submission
-6. Verify `capability_id` field description in `submit_payload`:
-   - References `list_capabilities` for available IDs
-   - Explains versioned capability format
-7. Verify `body` field description in `submit_payload`:
-   - References `list_capabilities` for schema requirements
-   - Explains structure should match capability expectations
-**Expected Results:**
-- `list_capabilities` tool description is clear and informative
-- `submit_payload` description references `list_capabilities`
-- Field descriptions guide users to discovery
-- Tool descriptions follow MCP protocol format
-**Machine-Checkable:**
-```bash
-test: "tests/integration/mcp_tool_descriptions.test.ts"
-```
-**Status:** ⏳ not_run
-### IT-004: Example Payload Validation Flow
-**Goal:** Verify that example payloads provided by `list_capabilities` are valid and can be used for submissions.
-**Batches Covered:** 0
-**FUs Involved:** FU-304, FU-201 (submit_payload)
-**Test Steps:**
-1. Call `list_capabilities` with no filters
-2. For each of the 5 capabilities:
-   - Extract `example_payload` from response
-   - Verify `example_payload` is non-empty
-   - Verify `example_payload` contains expected fields based on `canonicalization_fields`
-   - Verify `example_payload` structure matches capability type:
-     - Invoice: has `invoice_number`, `amount`, `vendor_name`, `customer_name`, `date`
-     - Transaction: has `transaction_id`, `amount`, `merchant_name`, `counterparty`, `date`
-     - Receipt: has `receipt_number`, `amount`, `vendor_name`, `date`
-     - Contract: has `contract_number`, `parties`, `start_date`, `end_date`
-     - Note: has `title`, `content`, `tasks`
-3. For each capability:
-   - Use `example_payload` as payload `body` in `submit_payload`
-   - Add required provenance metadata
-   - Submit payload via `submit_payload`
-   - Verify submission succeeds
-   - Verify entities extracted correctly
-**Expected Results:**
-- All 5 capabilities have valid example payloads
-- Example payloads contain expected fields
-- Example payloads can be used successfully in `submit_payload`
-- Submissions succeed with example payloads
-- Entities extracted correctly from example payloads
-**Machine-Checkable:**
-```bash
-test: "tests/integration/example_payload_validation.test.ts"
-```
-**Status:** ⏳ not_run
-### IT-005: MCP Protocol Compliance
-**Goal:** Verify that `list_capabilities` action follows MCP protocol specification.
-**Batches Covered:** 0
-**FUs Involved:** FU-304
-**Test Steps:**
-1. Verify `list_capabilities` tool definition in `ListTools` response:
-   - Has required `name` field
-   - Has required `description` field
-   - Has required `inputSchema` field
-   - `inputSchema` follows JSON Schema format
-2. Call `list_capabilities` with valid request
-3. Verify response structure follows MCP protocol:
-   - Returns object with `content` array
-   - `content` array contains objects with `type` and `text` fields
-   - `text` contains valid JSON string
-4. Parse JSON from response
-5. Verify parsed JSON matches response schema from specification
-6. Call `list_capabilities` with invalid request (invalid filter)
-7. Verify error response follows MCP error format:
-   - Contains error code (`VALIDATION_ERROR`)
-   - Contains error message
-   - Uses proper MCP error structure
-**Expected Results:**
-- Tool definition follows MCP protocol
-- Response structure follows MCP protocol
-- Parsed JSON matches specification
-- Error responses follow MCP error format
-- No protocol violations detected
-**Machine-Checkable:**
-```bash
-test: "tests/integration/mcp_protocol_compliance.test.ts"
-```
-**Status:** ⏳ not_run
-### IT-006: Backward Compatibility Validation
-**Goal:** Verify that adding `list_capabilities` doesn't break existing MCP integrations.
-**Batches Covered:** 0
-**FUs Involved:** FU-304, FU-201 (submit_payload), FU-202 (retrieve_records)
-**Test Steps:**
-1. Run existing v0.1.0 integration test suite
-2. Verify all existing MCP actions still functional:
-   - `submit_payload` works without using `list_capabilities`
-   - `retrieve_records` works as before
-   - `update_record` works as before
-   - `delete_record` works as before
-   - `upload_file` works as before
-   - `get_file_url` works as before
-3. Verify existing tool descriptions still accessible
-4. Verify no breaking changes to request/response schemas
-5. Verify existing capability IDs still accepted by `submit_payload`:
-   - `neotoma:store_invoice:v1`
-   - `neotoma:store_transaction:v1`
-   - `neotoma:store_receipt:v1`
-   - `neotoma:store_contract:v1`
-   - `neotoma:store_note:v1`
-6. Verify hardcoded capability IDs still work (no regression)
-**Expected Results:**
-- All existing integration tests pass
-- No breaking changes to existing actions
-- Existing capability IDs still accepted
-- Existing tool descriptions still accessible
-- Backward compatibility maintained
-**Machine-Checkable:**
-```bash
-test: "tests/integration/backward_compatibility.test.ts"
-```
-**Status:** ⏳ not_run
-### IT-007: Performance and Response Time
-**Goal:** Verify that `list_capabilities` meets response time targets.
-**Batches Covered:** 0
-**FUs Involved:** FU-304
-**Test Steps:**
-1. Call `list_capabilities` 100 times with no filters
-2. Measure response time for each call
-3. Calculate p50, p95, p99 response times
-4. Verify p95 response time < 100ms (target from acceptance criteria)
-5. Call `list_capabilities` 100 times with filters (intent and version)
-6. Measure response time for filtered calls
-7. Verify p95 response time < 100ms for filtered calls
-8. Verify no performance degradation compared to target
-9. Verify response times consistent across calls
-**Expected Results:**
-- p95 response time < 100ms (unfiltered)
-- p95 response time < 100ms (filtered)
-- Response times consistent across calls
-- No performance degradation
-- Capability registry access is efficient (static data)
-**Machine-Checkable:**
-```bash
-test: "tests/integration/list_capabilities_performance.test.ts"
-```
-**Status:** ⏳ not_run
-## Test Summary
-**Total Integration Tests:** 7
-**Test Coverage:**
-- ✅ Capability discovery workflow
-- ✅ Filtering logic (intent, version)
-- ✅ Tool description guidance
-- ✅ Example payload validation
-- ✅ MCP protocol compliance
-- ✅ Backward compatibility
-- ✅ Performance and response time
-**Test Files:**
-1. `tests/integration/list_capabilities_to_submission.test.ts`
-2. `tests/integration/list_capabilities_filtering.test.ts`
-3. `tests/integration/mcp_tool_descriptions.test.ts`
-4. `tests/integration/example_payload_validation.test.ts`
-5. `tests/integration/mcp_protocol_compliance.test.ts`
-6. `tests/integration/backward_compatibility.test.ts`
-7. `tests/integration/list_capabilities_performance.test.ts`
-**Pre-Deployment Checklist:**
-- [ ] All 7 integration tests passing
-- [ ] Response times within target (< 100ms p95)
-- [ ] Backward compatibility validated
-- [ ] MCP protocol compliance verified
-- [ ] Example payloads validated
-- [ ] Tool descriptions reviewed
-- [ ] No breaking changes detected
-
-
-
-

package/docs/releases/v0.2.2/manifest.yaml

@@ -1,108 +0,0 @@
-release:
-  id: "v0.2.2"
-  name: "list_capabilities MCP Action"
-  type: "not_marketed" # marketed | not_marketed
-  status: "planning" # planning | in_progress | in_testing | ready_for_deployment | deployed | completed
-  target_date: "when ready"
-  priority: "P0"
-  marketing_required: false
-
-# Execution strategy
-execution_strategy:
-  type: "single" # Single FU release
-  max_parallel_fus: 1
-  max_high_risk_in_parallel: 1
-  agent_spawning:
-    enabled: false # Single FU, no need for parallel execution
-    status_tracking: "file"
-    status_file: "docs/releases/v0.2.2/agent_status.json"
-
-feature_units:
-  # MCP Action — list_capabilities
-  - id: "FU-304"
-    priority: "P0"
-    dependencies: ["FU-200"] # MCP Server Core from v0.1.0
-    risk_level: "low"
-    notes: "New MCP action for dynamic capability discovery. Exposes existing capability registry via MCP."
-
-execution_schedule:
-  batches:
-    # Batch 0: list_capabilities MCP Action
-    - batch_id: 0
-      feature_units: ["FU-304"]
-      dependencies: ["FU-200"] # Assumes v0.1.0 FU-200 is complete
-
-checkpoints:
-  checkpoint_1_after_batch: 0 # Pre-release sign-off after implementation
-
-acceptance_criteria:
-  product:
-    - criterion: "list_capabilities MCP action returns all 5 capabilities with complete metadata"
-      test: "tests/integration/list_capabilities.test.ts"
-      metric: null
-    - criterion: "Filtering by intent and version works correctly"
-      test: "tests/integration/list_capabilities.test.ts"
-      metric: null
-    - criterion: "submit_payload tool description references list_capabilities"
-      test: "tests/integration/mcp_tool_descriptions.test.ts"
-      metric: null
-    - criterion: "All 5 existing capabilities discoverable"
-      test: "tests/integration/list_capabilities.test.ts"
-      metric: "capabilities_count == 5"
-  technical:
-    - criterion: "MCP action follows MCP protocol specification"
-      test: "tests/integration/mcp_protocol.test.ts"
-      metric: null
-    - criterion: "Response structure matches specification in docs/specs/MCP_SPEC.md"
-      test: "tests/integration/list_capabilities.test.ts"
-      metric: null
-    - criterion: "Example payloads generated for all 5 capabilities"
-      test: "tests/integration/list_capabilities.test.ts"
-      metric: "example_payloads_count == 5"
-    - criterion: "No breaking changes to existing MCP actions"
-      test: "tests/integration/backward_compatibility.test.ts"
-      metric: null
-    - criterion: "Response time < 100ms"
-      test: "tests/integration/list_capabilities_performance.test.ts"
-      metric: "response_time_p95 < 100"
-  business:
-    - criterion: "Integrations can discover available capabilities at runtime"
-      test: null
-      metric: "Manual validation via MCP client"
-    - criterion: "Self-documenting tool descriptions reduce support burden"
-      test: null
-      metric: "Manual validation of tool descriptions"
-
-pre_mortem:
-  failure_modes:
-    - mode: "MCP protocol compliance issues"
-      early_warning: "MCP integration tests fail, protocol compliance issues"
-      mitigation: "Follow existing MCP action patterns, comprehensive protocol tests"
-      rollback: "Revert MCP action changes, check protocol compliance"
-    - mode: "Response structure mismatch"
-      early_warning: "Integration tests fail, response structure doesn't match spec"
-      mitigation: "Comprehensive response schema validation, spec alignment checks"
-      rollback: "Fix response structure, re-validate against spec"
-    - mode: "Example payload generation failures"
-      early_warning: "Missing or invalid example payloads for capabilities"
-      mitigation: "Validate example payloads against capability schemas"
-      rollback: "Fix example payload generation, re-validate"
-    - mode: "Backward compatibility regressions"
-      early_warning: "Existing integration tests fail, breaking changes detected"
-      mitigation: "Comprehensive backward compatibility tests, no breaking changes"
-      rollback: "Revert changes, ensure backward compatibility maintained"
-
-deployment:
-  target: "production" # All releases deploy to production at neotoma.io
-  target_url: "neotoma.io"
-  marketing: false # Not marketed release - no marketing activities
-  rollback_plan: "Revert code changes and redeploy to neotoma.io; remove list_capabilities action from MCP server; existing integrations continue to work (backward compatible)"
-
-monitoring:
-  key_metrics:
-    - "list_capabilities_success_rate"
-    - "list_capabilities_response_time_p95"
-    - "list_capabilities_call_volume"
-    - "submit_payload_success_rate_post_release"
-    - "mcp_tool_description_access_count"
-