neotoma 0.3.0 → 0.3.2

package/foundation/.cursor/rules/plan_execution_testing.mdc

@@ -1,98 +0,0 @@
----
-description: "Implement tests as part of plan execution, not just skeleton files. Load when executing plans that include test tasks."
-alwaysApply: false
----
-# Plan Execution Testing Rule
-
-## Rule
-
-**When executing a plan that includes test implementation tasks, agents MUST implement the actual test logic, not just create skeleton test files with TODO comments.**
-
-## Requirements
-
-1. **Test Implementation is Mandatory:**
-   - When a plan includes "Write unit tests" or "Write integration tests" tasks, these MUST be fully implemented
-   - Tests must contain actual test logic, assertions, and mocks (where appropriate)
-   - Skeleton tests with only TODO comments are NOT acceptable
-
-2. **Test Coverage:**
-   - Unit tests should test individual functions/methods in isolation
-   - Integration tests should test end-to-end workflows with real database operations
-   - Tests should cover both happy paths and error cases
-   - Tests should validate edge cases and boundary conditions
-
-3. **Test Quality:**
-   - Tests must be runnable (no syntax errors, proper imports)
-   - Tests should use appropriate mocking for unit tests
-   - Tests should use real database operations for integration tests (with proper cleanup)
-   - Tests should follow existing test patterns in the codebase
-
-4. **When Tests Are Part of Plan:**
-   - If plan includes test tasks, implement them during plan execution
-   - Do NOT defer test implementation to "later" or mark as "TODO"
-   - Complete test implementation before marking test-related todos as completed
-
-## Examples
-
-### ❌ Incorrect (Skeleton Only)
-```typescript
-it("should return ineligible if field is blacklisted", async () => {
-  // TODO: Mock blacklist check
-  // const result = await service.checkAutoEnhancementEligibility(...);
-  // expect(result.eligible).toBe(false);
-});
-```
-
-### ✅ Correct (Fully Implemented)
-```typescript
-it("should return ineligible if field is blacklisted", async () => {
-  const mockBlacklistQuery = {
-    select: vi.fn().mockReturnThis(),
-    or: vi.fn().mockReturnThis(),
-    data: [{ field_pattern: "_test*" }],
-  };
-  mockFrom.mockReturnValueOnce(mockBlacklistQuery);
-
-  const result = await service.checkAutoEnhancementEligibility({
-    entity_type: "transaction",
-    fragment_key: "_test_field",
-    user_id: "test-user-id",
-  });
-
-  expect(result.eligible).toBe(false);
-  expect(result.reasoning).toContain("blacklisted");
-});
-```
-
-## Integration with Plan Execution
-
-When executing a plan:
-
-1. **Identify Test Tasks:**
-   - Look for todos with "test" in the description
-   - Check plan phases for "Testing" or "Test" sections
-
-2. **Implement Tests:**
-   - Create test files with full implementation
-   - Use existing test patterns from the codebase
-   - Ensure tests are runnable and follow conventions
-
-3. **Mark Todos Complete:**
-   - Only mark test todos as completed after tests are fully implemented
-   - Verify tests follow codebase patterns before completion
-
-## Constraints
-
-- **DO NOT** create test files with only TODO comments
-- **DO NOT** defer test implementation to "later"
-- **DO NOT** mark test todos as completed if tests are not implemented
-- **DO** implement full test logic during plan execution
-- **DO** follow existing test patterns in the codebase
-- **DO** ensure tests are runnable and properly structured
-
-## When This Applies
-
-- During plan execution when plan includes test tasks
-- When todos include "Write unit tests" or "Write integration tests"
-- When plan phases include testing requirements
-- Always when implementing features that require testing

package/foundation/.cursor/rules/post_build_testing.mdc

@@ -1,159 +0,0 @@
----
-description: "Describe manual test cases after completing a release build. Load when finishing a release build or describing verification steps."
-alwaysApply: false
----
-# Post-Build Testing Rule
-
-Configuration is read from `foundation-config.yaml`.
-
-Ensures agents always describe manual test cases after completing a release build.
-
-## Rule
-
-After completing a release build:
-
-1. **Generate or update release report** with Testing Guidance section containing:
-
-   - All manual test cases from integration tests file (if configured)
-   - Each test formatted as user-facing instructions
-   - Step-by-step actions (not technical commands)
-   - Expected results for each test
-
-2. **Present test cases to user** with:
-
-   - Summary: "After building this release, run the following manual test cases:"
-   - List of all test IDs and names
-   - Reference to Testing Guidance section in release report for detailed instructions
-
-3. **Include manual validation requirements** (if present in integration tests):
-   - Integration steps with external tools
-   - Manual verification steps
-
----
-
-## When This Applies
-
-- After release orchestrator completes all batches
-- After manual release build completion
-- When generating release reports (always include Testing Guidance section)
-- When user asks "what should I test?" after a build
-
-## Agent Actions
-
-### After Release Build Completes
-
-1. **Load configuration:**
-   - Read `foundation-config.yaml` for release directory settings
-   - Determine integration tests file location (if configured)
-
-2. **Load integration tests (if file exists):**
-
-   - Read `{configured_releases_directory}/in_progress/{RELEASE_ID}/integration_tests.md` (or configured filename)
-   - Extract all test definitions (ID, name, goal, steps, expected results)
-
-3. **Generate test case descriptions:**
-
-   - Format each test as user-facing instructions
-   - Convert technical steps to user actions
-   - Include expected results
-
-4. **Update release report:**
-
-   - Ensure Testing Guidance section exists and is populated
-   - Include all tests from integration tests file
-   - Format as manual test cases
-
-5. **Present to user:**
-
-   ```
-   Release build complete. To validate functionality, run these manual test cases:
-
-   See Testing Guidance section in release_report.md for detailed instructions:
-   - IT-001: Test Case Name
-   - IT-002: Test Case Name
-   ... (list all tests)
-
-   Each test includes step-by-step user actions and expected results.
-   ```
-
----
-
-## Test Case Format
-
-Each test case MUST include:
-
-```markdown
-#### {TEST_ID}: {TEST_NAME}
-
-**Goal:** {GOAL}
-
-**Steps to test:**
-
-1. {USER_ACTION_1}
-2. {USER_ACTION_2}
-   ...
-
-**Expected results:**
-
-- {EXPECTED_RESULT_1}
-- {EXPECTED_RESULT_2}
-```
-
-**Step conversion rules:**
-
-- "Call API `endpoint`" → "Call API `endpoint` via configured tools"
-- "Query database" → "Query using configured query tools"
-- "Verify X" → "Verify X matches expected behavior"
-- Remove technical implementation details
-- Keep user actions clear and actionable
-
----
-
-## Integration Points
-
-### Release Orchestrator
-
-After all batches complete:
-
-1. Run full integration test suite (if test files exist)
-2. Update `status.md` with test results
-3. **ALWAYS generate complete release report (REQUIRED)** - This is a mandatory step per `foundation/development/release_workflow.md` Step 1.4
-   - Report must exist before transitioning to `in_testing` status
-   - Report includes Testing Guidance section with all manual test cases
-   - Follow `docs/feature_units/standards/release_report_generation.md` for structure
-4. Log: "See release_report.md Testing Guidance section for manual test cases"
-
-### Release Report Generation
-
-Testing Guidance section is REQUIRED and must include:
-- All tests from integration tests file
-- Format as user-facing manual test cases
-- Include manual validation requirements
-
-### Manual Build Completion
-
-If release is built manually (not via orchestrator):
-- Still generate/update release report with Testing Guidance section
-- Present test cases to user
-
-## Constraints
-
-- Do NOT skip test case descriptions after build completion
-- Always include all tests from integration tests file (if it exists)
-- Always format as user-facing instructions (not developer commands)
-- Always reference Testing Guidance section in release report when presenting to user
-
-## Configuration
-
-Post-build testing uses paths from `foundation-config.yaml`:
-
-```yaml
-orchestration:
-  release:
-    enabled: true
-    directory: "docs/releases/"  # Or configured path
-    integration_tests_file: "integration_tests.md"  # Configurable
-    release_report_file: "release_report.md"  # Configurable
-    testing_section_name: "Testing Guidance"  # Configurable
-```
-

package/foundation/.cursor/rules/prefer_cli_tools.mdc

@@ -1,234 +0,0 @@
----
-description: "Prefer CLI tools over dashboard/UI for logs, DB queries, config, and admin tasks. Load when checking logs, configuring services, or querying data."
-alwaysApply: false
----
-
-# Prefer CLI Tools Rule
-
-**Reference:** `foundation/agent_instructions/cursor_rules/configuration_management.md` - Configuration management
-
-## Purpose
-
-Ensures agents always prefer CLI tools over dashboard/UI access when checking logs, configuring services, querying data, or performing administrative tasks. CLI tools are more automatable, scriptable, and provide better integration with development workflows.
-
-## Trigger Patterns
-
-When any of the following occur, agents MUST use CLI tools instead of dashboard/UI:
-
-- **Checking logs** (Supabase, SendGrid, application logs)
-- **Querying databases** (Supabase, PostgreSQL)
-- **Configuring services** (Supabase settings, SMTP, environment variables)
-- **Managing resources** (users, projects, deployments)
-- **Checking status** (service health, configuration state)
-- **Installing dependencies** (package managers, tools)
-
-## Agent Actions
-
-### Step 1: Check for Available CLI Tools
-
-Before suggesting dashboard access, check if CLI tools are available:
-
-1. **Check if tool is installed:**
-   ```bash
-   which supabase
-   which op
-   which gh
-   which aws
-   ```
-
-2. **Check if tool can be installed:**
-   - Package managers: `brew`, `npm`, `pip`
-   - Official installers
-   - Documentation for installation
-
-3. **Verify CLI has required functionality:**
-   - Check CLI documentation
-   - Test basic commands
-   - Verify authentication/configuration
-
-### Step 2: Use CLI Tools
-
-**For Supabase:**
-- Use `supabase` CLI for logs, configuration, database queries
-- Install if not available: `brew install supabase/tap/supabase`
-- Authenticate: `supabase login`
-
-**For 1Password:**
-- Use `op` CLI for credential access
-- Already required for environment variable management
-
-**For Git/GitHub:**
-- Use `git` CLI for all git operations
-- Use `gh` CLI for GitHub API operations
-
-**For Cloud Services:**
-- Use `aws` CLI for AWS services
-- Use `gcloud` CLI for Google Cloud
-- Use service-specific CLIs when available
-
-### Step 3: Provide Installation Instructions
-
-If CLI is not installed, provide installation steps:
-
-1. **Check installation method:**
-   - Homebrew (macOS): `brew install {tool}`
-   - npm: `npm install -g {tool}`
-   - Official installer
-   - Package manager
-
-2. **Provide authentication steps:**
-   - Login commands
-   - Configuration steps
-   - Credential setup
-
-3. **Verify installation:**
-   - Test command
-   - Check version
-   - Verify functionality
-
-## Examples
-
-### ✅ Correct: Use Supabase CLI for Logs
-
-```bash
-# Check if Supabase CLI is installed
-if ! command -v supabase &> /dev/null; then
-  echo "Installing Supabase CLI..."
-  brew install supabase/tap/supabase
-fi
-
-# View auth logs
-supabase projects logs --project-ref {PROJECT_ID} --type auth
-
-# Query database
-supabase db query "SELECT * FROM auth.users ORDER BY created_at DESC LIMIT 5"
-```
-
-### ✅ Correct: Use 1Password CLI
-
-```bash
-# Fetch credentials via CLI
-op item get "Sendgrid" --vault Private --fields "API key"
-```
-
-### ✅ Correct: Use GitHub CLI
-
-```bash
-# Check PR status
-gh pr list --state open
-
-# View logs
-gh run list --workflow=ci.yml
-```
-
-### ❌ Incorrect: Suggest Dashboard Access First
-
-```bash
-# WRONG - Don't suggest dashboard without checking CLI first
-echo "Go to Supabase Dashboard → Authentication → Logs"
-```
-
-### ❌ Incorrect: Skip CLI Installation
-
-```bash
-# WRONG - Don't skip CLI if it can be installed
-if ! command -v supabase &> /dev/null; then
-  echo "CLI not available, use dashboard"  # Should install CLI instead
-fi
-```
-
-## CLI Tools Priority
-
-**Always check for CLI tools in this order:**
-
-1. **Official CLI** (supabase, op, gh, aws, gcloud)
-2. **Package manager tools** (brew, npm, pip)
-3. **Script-based tools** (curl + API, custom scripts)
-4. **Dashboard/UI** (only as last resort)
-
-## Installation Commands
-
-**Common CLI tools:**
-
-```bash
-# Supabase CLI
-brew install supabase/tap/supabase
-
-# GitHub CLI
-brew install gh
-
-# AWS CLI
-brew install awscli
-
-# 1Password CLI (already required)
-brew install 1password-cli
-
-# Node.js tools
-npm install -g {package}
-
-# Python tools
-pip install {package}
-```
-
-## Constraints
-
-- **MUST check for CLI tools** before suggesting dashboard access
-- **MUST provide installation steps** if CLI is not installed
-- **MUST use CLI tools** when available and functional
-- **MUST NOT default to dashboard** without checking CLI first
-- **MUST verify CLI functionality** after installation
-
-## When Dashboard is Acceptable
-
-Dashboard/UI access is acceptable only when:
-
-1. **CLI tool doesn't exist** for the functionality
-2. **CLI tool is not available** and cannot be installed
-3. **CLI tool lacks required functionality** (rare edge cases)
-4. **User explicitly requests dashboard** access
-
-Even in these cases, document that CLI would be preferred if available.
-
-## Related Documents
-
-- `foundation/agent_instructions/cursor_rules/environment_variables_1password.mdc` - 1Password CLI usage
-- `foundation/agent_instructions/cursor_rules/configuration_management.md` - Configuration management
-
-## Agent Instructions
-
-### When to Load This Document
-
-Load this document when:
-- Checking logs or status
-- Configuring services
-- Querying databases
-- Managing resources
-- User requests dashboard access
-
-### Required Co-Loaded Documents
-
-- `foundation/agent_instructions/cursor_rules/configuration_management.md` - Configuration management
-- `foundation/agent_instructions/cursor_rules/environment_variables_1password.mdc` - CLI credential access
-
-### Constraints Agents Must Enforce
-
-1. Always check for CLI tools before suggesting dashboard access
-2. Provide installation steps if CLI is not installed
-3. Use CLI tools when available and functional
-4. Verify CLI functionality after installation
-5. Document CLI preference even when dashboard is used
-
-### Forbidden Patterns
-
-- Suggesting dashboard access without checking for CLI first
-- Skipping CLI installation when tool is available
-- Defaulting to dashboard without verifying CLI availability
-- Not providing CLI installation instructions
-
-### Validation Checklist
-
-- [ ] Checked for CLI tool availability (`which {tool}`)
-- [ ] Provided installation steps if CLI not installed
-- [ ] Used CLI tool for the task (if available)
-- [ ] Verified CLI functionality after installation
-- [ ] Documented CLI preference in scripts/docs

package/foundation/.cursor/rules/readme_maintenance.mdc

@@ -1,153 +0,0 @@
----
-description: "README.md must stay synchronized with documentation changes. Load when editing docs that affect project overview or when updating README."
-alwaysApply: false
----
-# README Maintenance Rule
-
-**Reference:** `README.md` — Project overview and entry point
-
-Ensures that `README.md` remains synchronized with documentation changes, providing accurate and comprehensive representation of the repository at all times.
-
-## Configuration
-
-This rule can be configured in `foundation-config.yaml`:
-
-```yaml
-tooling:
-  readme_generation:
-    enabled: true
-    source_documents: []  # List of source documents for regeneration
-    structure_template: null  # Path to README structure template
-    regenerate_triggers: []  # File patterns that trigger regeneration
-```
-
-## Trigger Patterns
-
-When any of the following occur, update `README.md`:
-
-- Documentation files are created, modified, or deleted:
-  - New documentation sections added (e.g., new subsystem docs, new integration guides)
-  - Architecture changes documented
-  - New features or capabilities added to specs
-  - Release status changes
-  - Testing standards updated
-  - Integration providers added or removed
-
-- User explicitly requests README update:
-  - "update README"
-  - "sync README with docs"
-  - "ensure README reflects [change]"
-
-- Significant changes to:
-  - Core features or capabilities
-  - Architecture or system design
-  - Development workflow or setup
-  - Documentation structure
-  - Current project status
-
-## Agent Actions
-
-README updates are mandatory and automatic - whenever documentation is updated in materially affecting ways, README must be regenerated (not patched) in the same workflow, not as a separate step.
-
-### Step 1: Detect Material Documentation Changes
-
-When modifying ANY documentation:
-
-1. **Determine if change is material:**
-
-   A change is material if it affects:
-   - Core identity or philosophy documents
-   - Product positioning or problem statement
-   - MVP scope or specifications
-   - Architecture or system design
-   - Features or capabilities
-   - Release status
-   - Documentation structure (new categories, reorganization)
-   - Development workflow (setup, scripts)
-   - Integrations (providers added/removed)
-   - Target users or personas
-
-2. **If material change detected:** Regenerate entire README using configured regeneration framework or template. Do NOT patch individual sections. Use primary sources to regenerate from scratch. Regenerate in same tool call batch as documentation changes.
-
-3. **If non-material change (typos, formatting, minor clarifications):**
-   - May patch specific sections if needed
-   - Still verify consistency with docs
-
-### Step 2: Regenerate README
-
-For material changes:
-
-1. **Follow regeneration process:**
-   - Read primary source documents (per configuration)
-   - Extract key information (value prop, features, architecture, etc.)
-   - Generate README following required section structure
-   - Apply content guidelines (tone, style, confident positioning)
-   - Verify all sections against source docs
-
-2. **Maintain README structure:**
-   - Follow exact section order from template or framework
-   - Preserve formatting patterns
-   - Keep all required sections
-
-3. **Verify completeness:**
-   - All major documentation areas represented
-   - All quick links functional
-   - Current status accurate
-   - Development instructions current
-   - All information matches source docs exactly
-
-### Step 3: Validate Changes
-
-Before completing:
-
-1. **Check for broken links:**
-   - Verify all documentation links resolve correctly
-   - Ensure relative paths are correct
-
-2. **Verify consistency:**
-   - README matches documentation content
-   - No contradictions between README and docs
-   - Terminology consistent across README and docs
-
-3. **Ensure accuracy:**
-   - Feature lists match current capabilities
-   - Architecture description matches architecture docs
-   - Status information is current
-
-## README Sections and Update Triggers
-
-Common README sections and their update triggers (customize per repository):
-
-| README Section              | Update Trigger                                |
-| --------------------------- | --------------------------------------------- |
-| **What It Does**            | Core workflow changes, new capabilities       |
-| **Architecture**            | Architecture docs modified, layer changes     |
-| **Releases**                | Release status changes, new releases added    |
-| **Quick Links**             | New documentation added, structure changes    |
-| **Development**            | Setup instructions changed, new scripts added |
-| **Documentation Structure** | New doc categories, reorganization            |
-| **Core Principles**         | Philosophy or principles updated              |
-| **Testing**                 | Testing standards updated, coverage changes   |
-
-## Constraints
-
-- Regenerate README (not patch) whenever documentation changes in materially affecting ways
-- Regenerate README automatically in same tool call batch as material documentation changes
-- Use configured regeneration framework or template for regeneration process
-- Regenerate from primary sources, not from existing README
-- Maintain README accuracy and completeness against source docs
-- Verify all links before completing regeneration
-- Do NOT patch individual sections for material changes (always regenerate)
-- Do NOT add information to README that contradicts documentation
-- Preserve README's role as entry point and overview document
-- Follow required section structure exactly as defined in template or framework
-- Ensure confident, positive tone throughout (not defensive)
-
-
-
-
-
-
-
-
-