neotoma 0.3.0 → 0.3.2

package/.claude/rules/git_remote_sync.md

@@ -1,242 +0,0 @@
----
-description: "Load when push is rejected or branch diverged: pull and merge before pushing; resolve conflicts; do not force push; same workflow for submodules."
-alwaysApply: false
----
-
-<!-- Source: foundation/agent_instructions/cursor_rules/git_remote_sync.mdc -->
-
-# Git Remote Sync Rule
-
-## Purpose
-
-Ensures agents always pull and merge remote changes before pushing, maintaining repository synchronization and preventing push rejections.
-
-## Trigger Patterns
-
-When any of the following occur, agents MUST pull and merge before pushing:
-
-- Push is rejected with "non-fast-forward" or "diverged branches" error
-- `git status` shows "Your branch and 'origin/main' have diverged"
-- `git status` shows "Your branch is behind 'origin/main'"
-- Remote changes detected during commit workflow
-- Push command is about to execute
-- Any git operation that would modify remote state
-
-## Agent Actions
-
-### Step 1: Detect Remote Changes
-
-Before pushing or when push fails:
-
-1. **Check if remote is ahead:**
-   ```bash
-   git fetch origin
-   LOCAL=$(git rev-parse @)
-   REMOTE=$(git rev-parse @{u} 2>/dev/null || echo "")
-   
-   if [ -z "$REMOTE" ]; then
-     # No upstream set - proceed with push
-     exit 0
-   fi
-   
-   BASE=$(git merge-base @ @{u})
-   
-   if [ "$LOCAL" = "$REMOTE" ]; then
-     # Already in sync
-     exit 0
-   elif [ "$REMOTE" = "$BASE" ]; then
-     # Local is ahead - safe to push
-     exit 0
-   elif [ "$LOCAL" = "$BASE" ] || [ "$LOCAL" != "$REMOTE" ] && [ "$REMOTE" != "$BASE" ]; then
-     # Remote is ahead or branches have diverged - MUST pull and merge
-     PULL_NEEDED=true
-   fi
-   ```
-
-2. **If push was rejected, check error message:**
-   ```bash
-   # If push fails with "non-fast-forward" or "diverged"
-   # Immediately proceed to pull and merge workflow
-   ```
-
-### Step 2: Pull and Merge
-
-If remote changes detected:
-
-1. **Pull with merge strategy:**
-   ```bash
-   CURRENT_BRANCH=$(git branch --show-current)
-   git pull origin "$CURRENT_BRANCH" --no-rebase --no-edit
-   ```
-
-2. **Handle merge conflicts:**
-   - If conflicts occur, resolve them immediately
-   - Stage resolved files: `git add <resolved-files>`
-   - Complete merge: `git commit --no-edit` (or with merge message if needed)
-   - DO NOT abort merge unless user explicitly requests
-
-3. **Verify merge completed:**
-   ```bash
-   if git status | grep -q "Unmerged paths"; then
-     echo "❌ Merge conflicts still exist - resolve before proceeding"
-     exit 1
-   fi
-   ```
-
-### Step 3: Push After Merge
-
-After successful merge:
-
-1. **Push merged changes:**
-   ```bash
-   git push origin HEAD
-   ```
-
-2. **Verify push succeeded:**
-   ```bash
-   if [ $? -eq 0 ]; then
-     echo "✅ Successfully pushed after merging remote changes"
-   else
-     echo "❌ Push failed after merge - investigate"
-     exit 1
-   fi
-   ```
-
-## Workflow Integration
-
-### During Commit Workflow
-
-When executing commit command:
-
-1. **Before staging:** Check for remote changes
-2. **If remote changes exist:** Pull and merge first, then proceed with commit
-3. **After commit:** Push (which will succeed since we're now in sync)
-
-### During Push Operations
-
-When push is requested:
-
-1. **Before push:** Always check for remote changes
-2. **If remote changes exist:** Pull and merge first
-3. **Then push:** Execute push after merge completes
-
-### During Submodule Operations
-
-When committing/pushing submodules:
-
-1. **For each submodule:** Check remote status
-2. **If remote changes:** Pull and merge in submodule
-3. **Then push:** Push submodule after merge
-4. **Update main repo:** Update submodule reference in main repo
-
-## Constraints
-
-- MUST pull and merge before pushing when remote changes detected
-- MUST NOT skip pull step even if it seems unnecessary
-- MUST resolve merge conflicts immediately (do not leave in conflicted state)
-- MUST verify merge completed successfully before pushing
-- MUST NOT force push to override remote changes
-- MUST handle submodules with same pull-merge-push workflow
-
-## Error Handling
-
-### Merge Conflicts
-
-If merge conflicts occur:
-
-1. **List conflicted files:**
-   ```bash
-   git status | grep "both modified\|both added\|deleted by them\|deleted by us"
-   ```
-
-2. **Resolve conflicts:**
-   - Read conflicted files
-   - Resolve using appropriate strategy (keep local, keep remote, or merge)
-   - Stage resolved files: `git add <file>`
-
-3. **Complete merge:**
-   ```bash
-   git commit --no-edit
-   ```
-
-### Push Still Fails After Merge
-
-If push fails after merge:
-
-1. **Re-check remote status:**
-   ```bash
-   git fetch origin
-   git status
-   ```
-
-2. **Verify local is ahead or in sync:**
-   ```bash
-   LOCAL=$(git rev-parse @)
-   REMOTE=$(git rev-parse @{u})
-   BASE=$(git merge-base @ @{u})
-   
-   if [ "$REMOTE" = "$BASE" ]; then
-     # Local is ahead - push should work
-     git push origin HEAD
-   else
-     # Still diverged - pull again
-     git pull origin "$CURRENT_BRANCH" --no-rebase
-   fi
-   ```
-
-## Configuration
-
-No configuration required - this rule applies universally to all git operations.
-
-## Examples
-
-### Example 1: Push Rejected
-
-```bash
-$ git push origin HEAD
-! [rejected]        HEAD -> main (non-fast-forward)
-error: failed to push some refs
-
-# Agent automatically:
-1. git fetch origin
-2. git pull origin main --no-rebase --no-edit
-3. Resolve conflicts if any
-4. git push origin HEAD
-```
-
-### Example 2: Pre-Push Check
-
-```bash
-# Before pushing, agent checks:
-$ git fetch origin
-$ git status
-Your branch and 'origin/main' have diverged
-
-# Agent automatically:
-1. git pull origin main --no-rebase --no-edit
-2. Resolve conflicts if any
-3. git push origin HEAD
-```
-
-### Example 3: Submodule Sync
-
-```bash
-# Committing foundation submodule
-$ cd foundation
-$ git push origin HEAD
-! [rejected]        HEAD -> main (non-fast-forward)
-
-# Agent automatically:
-1. git pull origin main --no-rebase --no-edit
-2. Resolve conflicts if any
-3. git push origin HEAD
-4. cd ..
-5. git add foundation
-6. git commit -m "Update foundation submodule"
-```
-
-## Related Documents
-
-- `foundation/agent_instructions/cursor_commands/pull.md` - Pull command workflow
-- `foundation/agent_instructions/cursor_commands/commit.md` - Commit command workflow
-- `foundation/development/workflow.md` - Git workflow documentation

package/.claude/rules/instruction_documentation.md

@@ -1,287 +0,0 @@
----
-description: "When user says 'always X' or 'never Y', or when creating/editing rule or command files: document the instruction in the correct rule file (foundation vs repo), use RFC 2119, run setup_cursor_copies after editing. Load when documenting constraints, adding rules, or editing .cursor/rules or foundation/agent_instructions sources."
-alwaysApply: false
----
-
-<!-- Source: foundation/agent_instructions/cursor_rules/instruction_documentation.mdc -->
-
-
-# Instruction Documentation Rule
-
-_(Cursor Rule: Agent Behavior)_
-
----
-
-## Purpose
-
-This document defines how agents MUST document important instructions, constraints, and guidelines in appropriate files. It ensures all instructions are available to Cursor agents via the symlinked rule structure, avoiding single points of failure.
-
-## Scope
-
-This rule covers:
-
-- When and how to document "always" and "never" instructions
-- Where to place rules (global vs repository-specific)
-- How rules are discovered via symlink structure
-- Format standards for rule files
-
-This rule does NOT cover:
-
-- Content of specific rules (covered by individual rule files)
-- Documentation standards for non-rule documentation (see `foundation/conventions/documentation_standards.md`)
-
-## Configuration
-
-All instructions are Cursor rules, stored in two scopes:
-
-```yaml
-cursor_rules:
-  # Global rules (for all repos using foundation)
-  global:
-    enabled: true
-    location: "foundation/agent_instructions/cursor_rules/"
-
-  # Repository-specific rules (for this repo only)
-  repository:
-    enabled: true
-    # Examples of common locations (choose appropriate docs/ subdirectory based on topic):
-    example_locations:
-      - "docs/conventions/" # Code and documentation conventions
-      - "docs/foundation/" # Foundation and architectural rules
-      - "docs/feature_units/standards/" # Feature unit workflow rules
-      - "docs/developer/" # Development workflow rules
-```
-
-**Note:** All `*_rules.md` files in `docs/` are automatically symlinked to `.claude/rules/` via the setup script. No central reference file is needed. Rules are discoverable via the symlink structure.
-
-## Trigger Patterns
-
-Agents MUST document instructions immediately during the same conversation, before proceeding with other work.
-
-**High-priority triggers:**
-
-- "always do X" or "never do Y"
-- "remember to" or "make sure to"
-- "all agents should" or "everyone must"
-
-**Standard triggers:**
-
-- Code style, patterns, conventions
-- Architectural constraints or boundaries
-- Workflow processes or procedures
-- Testing requirements or standards
-- Documentation standards
-- Security or privacy requirements
-- Error handling or validation rules
-- Repository-wide policies
-
-## Meta-Rule: Creating Rules
-
-When user says "always X" or "never Y", agents MUST:
-
-1. Recognize as rule creation request (all rules are Cursor rules)
-2. Determine scope:
-   - **Global rule** (benefits all repos using foundation): `foundation/agent_instructions/cursor_rules/{topic}.mdc` (MUST use `.mdc` extension)
-   - **Repository rule** (this repo only): Place in appropriate `docs/` subdirectory based on topic. MUST NOT use `.claude/rules/`
-     - Examples (choose subdirectory that best matches rule's topic):
-       - Code/documentation conventions → `docs/conventions/{topic}_rules.md`
-       - Foundation/architectural → `docs/foundation/{topic}_rules.md`
-       - Feature unit workflows → `docs/feature_units/standards/{topic}_rules.md`
-       - Development workflows → `docs/developer/{topic}_rules.md`
-3. Create rule immediately without asking for confirmation
-4. Update references (foundation README for global rules, repo docs for repository rules)
-
-**Decision tree:**
-
-- Benefits ALL repos using foundation → Global rule (`foundation/agent_instructions/cursor_rules/`)
-- Generic agent behavior → Global rule (`foundation/agent_instructions/cursor_rules/`)
-- Repository-specific domain/architecture → Repository rule (appropriate `docs/` subdirectory)
-- Project-specific features/constraints → Repository rule (appropriate `docs/` subdirectory)
-
-## Instruction Classification
-
-Rules are classified by scope and topic:
-
-**Global rules:**
-
-- Location: `foundation/agent_instructions/cursor_rules/`
-- Scope: All repos using foundation
-- Examples: Generic agent behavior, cross-repo patterns
-
-**Repository rules:**
-
-- Location: Appropriate `docs/` subdirectory based on topic
-- Scope: This repo only
-- Examples:
-  - Workflow/process instructions → `docs/feature_units/standards/` or `docs/developer/`
-  - Architectural constraints → `docs/foundation/` or `docs/architecture/`
-  - Code conventions → `docs/conventions/`
-- MUST NOT use `.claude/rules/` directly (rules are symlinked automatically)
-
-## Documenting Instructions
-
-**For repository-wide agent instructions:**
-
-1. Search `docs/` for existing `*_rules.md` files that match the instruction topic
-2. Add instruction to appropriate rule file using RFC 2119 directive language
-3. Create new rule file if no appropriate existing file exists (see "For Cursor rules" below)
-
-**For Cursor rules (all rules are Cursor rules):**
-
-1. Determine scope:
-   - **Global rule** (all repos) → `foundation/agent_instructions/cursor_rules/{topic}.mdc` (MUST use `.mdc` extension)
-   - **Repository rule** (this repo) → `docs/{appropriate_subdirectory}/{topic}_rules.md` based on topic
-     - Examples (choose subdirectory that best matches rule's topic):
-       - Code/documentation conventions → `docs/conventions/`
-       - Foundation/architectural → `docs/foundation/`
-       - Feature unit workflows → `docs/feature_units/standards/`
-       - Development workflows → `docs/developer/`
-2. MUST NOT use `.claude/rules/` directly
-3. Use filename:
-   - Foundation rules: `{topic}.mdc` or `{topic}_management.mdc` (MUST use `.mdc`)
-   - Repository rules: `{topic}_rules.md` or `{topic}_management.md`
-4. Follow existing rule format (Purpose, Trigger Patterns, Agent Actions, Constraints)
-5. Update references if applicable
-
-**For documentation-only instructions (not rules):**
-
-1. Document in appropriate `docs/` subdirectory based on topic
-2. MUST NOT store documentation in repo root
-3. Store temporary assessment/analysis files in `tmp/` directory
-4. Update references if applicable
-
-## Format Standards
-
-**Cursor rule format (MUST follow this structure):**
-
-```markdown
-# Rule Title
-
-## Purpose
-
-Clear statement of what this rule ensures.
-
-## Trigger Patterns
-
-When [conditions], agents MUST [action].
-
-## Agent Actions
-
-### Step 1: [Action]
-
-1. [Specific action]
-2. [Specific action]
-
-## Constraints
-
-- MUST / MUST NOT statements (per RFC 2119)
-- ALWAYS / NEVER statements
-```
-
-**Language requirements:**
-
-- Use RFC 2119 terminology: MUST, MUST NOT, SHOULD, SHOULD NOT, MAY
-- Use directive tone: clear, unambiguous statements
-- MUST NOT use vague qualifiers: "maybe", "perhaps", "possibly"
-- MUST NOT use marketing language: "powerful", "seamless", "revolutionary"
-- Use simple, declarative sentences with active voice
-
-## Workflow
-
-When user provides instructions (especially "always" or "never"), agents MUST:
-
-1. Detect trigger pattern
-2. Acknowledge: "Documenting instruction permanently in [location]"
-3. Classify instruction type and determine rule scope (apply Meta-Rule above)
-4. Document immediately (same conversation):
-   - Read target documentation file if it exists
-   - Add instruction using proper format
-   - Create or update rule file if needed
-   - Update references if new rule created
-   - Use directive language per RFC 2119 (MUST/SHOULD/MUST NOT/ALWAYS/NEVER)
-5. Update downstream documentation if applicable (see `downstream_doc_updates.md`)
-6. Confirm completion with details
-
-**MUST NOT:**
-
-- Skip documentation and proceed with other work
-- Promise to document "later" or in future conversation
-- Document only in conversation memory
-- Assume instruction is temporary
-
-**Before starting work:**
-
-1. Load required rules (rule files from symlinked locations)
-2. Verify instructions are current
-
-## Constraints
-
-Agents MUST:
-
-- Document "always" and "never" instructions immediately during same conversation
-- Classify instruction type before documenting
-- Use directive language per RFC 2119 (MUST/SHOULD/MUST NOT/ALWAYS/NEVER)
-- Ensure instructions are discoverable via symlink structure (global: `foundation/agent_instructions/cursor_rules/`, repository: `docs/` subdirectories)
-- Update downstream documentation when upstream docs change
-- Store temporary assessment/analysis files in `tmp/` directory
-
-Agents MUST NOT:
-
-- Defer documentation to future conversation
-- Document only in conversation memory
-- Duplicate instructions across multiple files without cross-references
-- Store documentation files in repo root
-- Store temporary assessment/analysis files in `docs/`
-- Use `.claude/rules/` directly (rules are symlinked automatically)
-
-## Availability
-
-Cursor agents automatically have access to all rules via symlink structure:
-
-1. **Global rules**: `foundation/agent_instructions/cursor_rules/` files are symlinked to `.claude/rules/` with `foundation_` prefix
-2. **Repository rules**: All `*_rules.md` files in `docs/` subdirectories are automatically symlinked to `.claude/rules/` via setup script
-3. **No central reference file needed**: Rules are discoverable directly via symlink structure
-
----
-
-## Agent Instructions
-
-### When to Load This Document
-
-Load this document when:
-
-- User provides "always" or "never" instructions
-- Creating or updating rule files
-- Determining where to place new instructions
-- Reviewing rule structure and organization
-
-### Required Co-Loaded Documents
-
-- `foundation/conventions/documentation_standards.md` (for format standards)
-
-### Constraints Agents Must Enforce
-
-1. All "always" and "never" instructions MUST be documented immediately in same conversation
-2. Rules MUST use RFC 2119 terminology (MUST, MUST NOT, SHOULD, SHOULD NOT, MAY)
-3. Rules MUST follow the format structure defined in Format Standards section
-4. Repository rules MUST be placed in appropriate `docs/` subdirectory based on topic
-5. Global rules MUST be placed in `foundation/agent_instructions/cursor_rules/`
-6. Agents MUST NOT use `.claude/rules/` directly (rules are symlinked automatically)
-7. Agents MUST NOT defer documentation to future conversations
-
-### Forbidden Patterns
-
-- Documenting instructions only in conversation memory
-- Creating rules in `.claude/rules/` directly
-- Using vague language instead of RFC 2119 terminology
-- Deferring rule creation to later conversations
-- Duplicating instructions across multiple files without cross-references
-
-### Validation Checklist
-
-- [ ] Rule file follows format structure (Purpose, Trigger Patterns, Agent Actions, Constraints)
-- [ ] Rule uses RFC 2119 terminology correctly
-- [ ] Rule is placed in correct location (global vs repository, appropriate subdirectory)
-- [ ] Rule file uses `*_rules.md` naming convention
-- [ ] No references to non-existent central reference files
-- [ ] Instructions documented immediately during same conversation

package/.claude/rules/native_browser_debugging.md

@@ -1,68 +0,0 @@
----
-description: "Load when debugging or verifying UI flows, OAuth, or frontend behavior: use native browser tools to reproduce and confirm; check console for errors; do not claim UI fixes without browser confirmation."
-alwaysApply: false
----
-
-<!-- Source: foundation/agent_instructions/cursor_rules/native_browser_debugging.mdc -->
-
-
-# Native Browser Debugging Rule
-
-## Purpose
-
-Ensure debugging and verification use the native browser for UI flows.
-
-## Trigger Patterns
-
-When investigating or verifying UI issues, OAuth flows, or frontend behavior.
-
-## Agent Actions
-
-1. Use the native browser tools for reproduction and verification.
-2. **Check browser console for errors** when making UI changes:
-   - Use browser MCP tools (`browser_console_messages`) to check for console errors
-   - Verify no `Uncaught SyntaxError`, `Uncaught TypeError`, or missing export errors
-   - Fix all console errors before marking UI changes complete
-3. Capture runtime evidence in the native browser before claiming resolution.
-4. Use Playwright only as supplemental coverage, not as the primary confirmation step.
-
-## Constraints
-
-- MUST use the native browser to reproduce UI issues when possible.
-- MUST use the native browser to confirm fixes for UI flows.
-- **MUST check browser console for errors** when making UI-impacting changes.
-- **MUST fix all console errors** (import/export errors, runtime errors) before marking UI changes complete.
-- MUST NOT claim UI fixes without native browser confirmation.
-- **MUST NOT mark UI changes complete** if console errors exist.
-
-## Agent Instructions
-
-### When to Load This Document
-
-Load when debugging UI flows or confirming UI fixes.
-
-### Required Co-Loaded Documents
-
-- Repository documentation standards
-
-### Constraints Agents Must Enforce
-
-1. Use native browser tooling for UI debugging and verification.
-2. Collect runtime evidence from the native browser before concluding resolution.
-3. Check browser console for errors after all UI changes.
-4. Fix all console errors before marking UI work complete.
-
-### Forbidden Patterns
-
-- Declaring UI bugs fixed without native browser verification.
-- Relying only on headless tests for UI verification.
-- Ignoring console errors in the browser.
-- Marking UI changes complete with console errors present.
-
-### Validation Checklist
-
-- [ ] Native browser used to reproduce the issue
-- [ ] Native browser used to confirm the fix
-- [ ] **Browser console checked for errors** (using `browser_console_messages` MCP tool)
-- [ ] **No console errors present** (no import/export errors, no runtime errors)
-- [ ] Runtime evidence captured during reproduction and verification

package/.claude/rules/plan_execution_testing.md

@@ -1,101 +0,0 @@
----
-description: "Load when executing a plan that includes test tasks: implement full test logic and assertions, not skeleton TODOs; run tests; mark test todos complete only after tests are implemented."
-alwaysApply: false
----
-
-<!-- Source: foundation/agent_instructions/cursor_rules/plan_execution_testing.mdc -->
-
-# 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