neotoma 0.3.0 → 0.3.2

package/.claude/rules/autonomous_execution.md

@@ -1,119 +0,0 @@
----
-description: "Load when deciding whether to ask user: proceed without asking for routine implementation, tests, docs, lint; stop and ask only for unclear architectural/design choices with high stakes (schema, layer boundaries, consistency model)."
-alwaysApply: false
----
-
-<!-- Source: foundation/agent_instructions/cursor_rules/autonomous_execution.mdc -->
-
-# Autonomous Execution Rule
-
-## Purpose
-
-Ensures agents proceed autonomously for routine work, stopping only for high-stakes architectural/design ambiguities that could lead to substantively wrong implementation if answered incorrectly.
-
-## Scope
-
-This rule defines:
-- When to proceed without asking
-- When to stop and ask the user
-- How to phrase questions when necessary
-- Alignment with risk management hold points
-
-## Proceed Without Asking
-
-**Execute immediately without confirmation for:**
-
-1. **Routine implementation**: Implementing features, refactors, bug fixes where the approach is clear from docs/codebase
-2. **Tests**: Writing unit tests, integration tests, E2E tests per testing standards
-3. **Documentation**: Updating docs to reflect code changes, fixing doc errors, adding missing documentation
-4. **Lint fixes**: Fixing linter errors, type errors, formatting issues
-5. **Code style**: Applying code conventions, normalizing naming, organizing imports
-6. **Allowed tool use**: Running any Bash commands, edits, or reads allowed by permissions in settings
-7. **Clear requirements**: Any task where the docs, codebase, or user request provide a clear answer
-
-**Do NOT ask for confirmation** before:
-- Making edits (permissions already grant Edit)
-- Running npm scripts, git commands, or other allowed Bash commands
-- Running tests or type checks
-- Fixing obvious issues (typos, broken imports, syntax errors)
-
-## Stop and Ask Only When
-
-**Stop and ask the user ONLY when ALL of these are true:**
-
-1. **Unclear architectural or design choice**: There is ambiguity about:
-   - Where to put a new module (which subsystem, which layer)
-   - Which abstraction to use (repository pattern, service pattern, reducer pattern)
-   - How to cross subsystem boundaries (direct import, event, API)
-   - Which consistency model to use (strong, eventual, bounded)
-   - Data model changes (new tables, new entity types, new relationships)
-
-2. **High stakes**: Choosing wrong would likely cause:
-   - Wrong layer (strategy/execution logic in Truth Layer)
-   - Wrong consistency model (eventual when strong required)
-   - Violating architectural boundaries (cross-layer dependencies)
-   - Breaking determinism (introducing nondeterministic logic)
-   - Breaking immutability (modifying observations/source after creation)
-   - Security issues (exposing PII, bypassing auth)
-
-**When asking:**
-- **Be concise**: Short, concrete question (1-2 sentences)
-- **Provide options**: "Proceed with X unless you prefer Y" or "Option A vs Option B?"
-- **State consequences**: "X would mean..., Y would mean..."
-- **Default to safe choice**: "I'll proceed with X (safe choice) unless you want Y"
-
-**Example good questions:**
-- "New `schema_registry` module: add to `src/services/` or create `src/schema/`? I'll use `src/services/` unless you prefer a separate directory."
-- "Cross-subsystem call: import directly or emit event? Direct is simpler but tighter coupling; event adds complexity. Proceed with direct import?"
-- "New `preferences` table: strong consistency (like entities) or eventual (like search)? I'll use strong unless you prefer eventual."
-
-## Do NOT Ask For
-
-**Never ask for confirmation when:**
-- Task is clearly specified in the prompt or docs ("should I do X?" when X is the task)
-- Fixing obvious errors ("is this correct?" for syntax errors, broken imports)
-- Running allowed tools (permissions already grant access)
-- Implementation details when approach is clear (function naming, file organization within established patterns)
-- Completing sub-tasks of an approved task (user asked for feature X, don't ask to implement each function)
-
-## Alignment with Risk Management
-
-This rule aligns with hold points from `risk_management.md`:
-
-**High-risk triggers that warrant asking:**
-- Schema changes (table structure, breaking JSONB changes)
-- Foundation document changes (files in configured foundation docs path)
-- Security changes (auth, RLS, encryption)
-- Architectural changes (layer boundaries, consistency models)
-- Violating documented constraints (even if user requests)
-
-**Medium/low-risk work that should proceed:**
-- New features within scope (no schema changes, no new subsystems)
-- API endpoint additions (following existing patterns)
-- Logic changes in non-critical paths
-- UI changes, documentation, tests
-
-## Configuration
-
-This rule is always loaded. No additional configuration needed.
-
-Permissions in settings already configured for autonomous execution (defaultMode, allow rules).
-
-## Constraints
-
-- **MUST proceed** without asking for routine work
-- **MUST stop** and ask only for high-stakes architectural/design ambiguity
-- **MUST phrase questions** concisely with options and defaults
-- **MUST NOT ask** for confirmation on allowed tool use
-- **MUST NOT ask** "should I do X?" when X is the specified task
-
-## Validation Checklist
-
-Before asking a question, verify:
-- [ ] Is there genuine architectural/design ambiguity?
-- [ ] Would choosing wrong cause substantively wrong implementation?
-- [ ] Can I find the answer in docs/codebase? (If yes, don't ask)
-- [ ] Have I phrased the question concisely with options?
-- [ ] Am I providing a safe default?
-
-If any of the first two are "no", proceed without asking.

package/.claude/rules/bug_fix_detection.md

@@ -1,145 +0,0 @@
----
-description: "Load when user mentions bug, error, fix, broken, not working, failing, issue, regression, or provides error messages/stack traces: run bug fix workflow (identify feature, classify, add regression test, fix)."
-alwaysApply: false
----
-
-<!-- Source: foundation/agent_instructions/cursor_rules/bug_fix_detection.mdc -->
-
-# Bug Fix Detection Rule
-
-**Reference:** `foundation/agent_instructions/cursor_commands/fix_feature_bug.md` — Bug fix workflow (or `.claude/skills/foundation_fix_feature_bug.md` if symlinked)
-
-Configuration is read from `foundation-config.yaml`.
-
-## Trigger Patterns
-
-When a user mentions any of the following patterns, automatically detect bug fix intent:
-
-- "bug"
-- "error"
-- "fix"
-- "broken"
-- "not working"
-- "failing"
-- "issue" (in context of problems)
-- "problem" (in context of code/functionality)
-- Error messages or stack traces
-- Test failures
-- "regression"
-- "broken feature"
-- "doesn't work"
-
-## Agent Actions
-
-### Step 1: Detection and Confirmation
-
-If context suggests a bug (mentions "bug", "error", "fix", "broken", error messages, etc.):
-
-1. **Extract bug information** from context:
-   - Error messages or stack traces (if provided)
-   - Feature/module ID (if mentioned or can be inferred from path/context)
-   - Description of the problem
-   - Steps to reproduce (if mentioned)
-
-2. **Identify affected feature/module:**
-   - Check error messages for file paths
-   - Check context for feature mentions
-   - Check open files for feature references
-   - If cannot identify → ask user: "Which feature/module is affected? (identifier or 'unknown')"
-
-3. **Ask for confirmation:**
-   ```
-   I see you're reporting a bug. Should I fix this using the bug fix workflow? 
-   Feature/Module: {identifier} (or 'unknown' if not identified)
-   (yes/no)
-   ```
-
-4. **Exception handling:**
-   - If user says "no" → do not proceed with bug fix workflow
-   - If user says "just document it" → document the bug instead
-
-### Step 2: Execute Bug Fix Workflow
-
-**If user confirms (yes):**
-
-1. **Load configuration:**
-   - Read `foundation-config.yaml` to get bug fix workflow settings
-   - Check if error classification is configured
-   - Determine feature unit directory (if feature units enabled)
-
-2. **Load required documents:**
-   - `foundation/agent_instructions/cursor_commands/fix_feature_bug.md` (command implementation, or `.claude/skills/foundation_fix_feature_bug.md` if symlinked)
-   - Repository navigation guide (if configured)
-   - Feature spec and manifest (if feature units enabled and identifier provided)
-   - Error classification documentation (if configured)
-   - Relevant subsystem/module docs (if configured)
-
-3. **Follow the bug fix workflow:**
-   - Identify feature/module from error, path, or context
-   - Load spec and manifest (if available)
-   - Classify bug using configured error classification (if available)
-   - Apply correction rules based on classification
-   - Always add a regression test
-   - Run tests
-
-4. **Output:**
-   - Error class (if classification configured)
-   - Reason for classification
-   - Corrected files
-   - Tests added/updated
-
-## Error Classification (Configurable)
-
-If error classification is configured in `foundation-config.yaml`, classify bugs into configured classes. Example classification:
-
-- **Class 1:** Implementation bug, spec is correct, code doesn't match spec
-- **Class 2:** Spec bug, spec is incomplete or wrong, code matches spec but spec is wrong
-- **Class 3:** Architectural bug, subsystem/architecture docs are wrong or incomplete
-
-**Correction rules (if classification configured):**
-- Class 1: Patch code only
-- Class 2: Update spec/manifest first, then align code/tests
-- Class 3: Update architecture docs first, then rebuild
-
-## Constraints
-
-- Do NOT proceed without user confirmation - always ask before fixing bugs
-- Always classify error if classification is configured
-- Always add regression test - never fix without test
-- Always run tests after fix
-- Always update spec/manifest for Class 2 bugs (if classification configured)
-- Always update architecture docs for Class 3 bugs (if classification configured)
-
-## Integration with Commands
-
-This rule complements the explicit `/fix_feature_bug` command:
-- **Rule-based detection:** Triggers automatically when bug patterns are detected
-- **Explicit command:** User can call `/fix_feature_bug` directly
-
-Both paths lead to the same workflow execution.
-
-## Configuration
-
-Bug fix detection uses settings from `foundation-config.yaml`:
-
-```yaml
-development:
-  bug_fix:
-    enabled: true
-    error_classification:
-      enabled: false  # Enable if you have error classification system
-      classes:
-        - name: "Class 1"
-          description: "Implementation bug"
-          correction: "Patch code only"
-        - name: "Class 2"
-          description: "Spec bug"
-          correction: "Update spec first, then code"
-        - name: "Class 3"
-          description: "Architectural bug"
-          correction: "Update architecture docs first"
-    require_regression_test: true
-    test_commands:  # Optional, repo-specific test commands
-      - "npm test"
-      - "npm run test:integration"
-```

package/.claude/rules/bug_learning.md

@@ -1,154 +0,0 @@
----
-alwaysApply: true
----
-
-<!-- Source: foundation/agent_instructions/cursor_rules/bug_learning.mdc -->
-
-
-# Bug Learning and Continuous Improvement Rules
-
-## Purpose
-
-Ensures that when bugs are discovered, agents systematically improve both test coverage and foundation rules to prevent similar bugs in the future.
-
-## Scope
-
-This document covers:
-- Required actions when bugs are discovered
-- Test coverage improvement requirements
-- Foundation rule generalization process
-- Learning documentation requirements
-
-This document does NOT cover:
-- Bug fix workflow (see foundation `bug_fix_detection.mdc`)
-- Testing standards (see repository testing standards)
-- Rule creation process (see foundation `instruction_documentation.mdc`)
-
-## Core Instruction
-
-**ALWAYS increase automated test coverage and integrate learnings into foundation rules when bugs are found.**
-
-## Trigger Patterns
-
-When any bug is discovered through:
-- Manual testing
-- Production incidents
-- User reports
-- Integration testing gaps
-- Code review findings
-- Runtime errors
-
-Agents MUST:
-1. Fix the bug
-2. Add regression test
-3. Analyze why existing tests missed it
-4. Strengthen test coverage
-5. Evaluate if learnings should be generalized to foundation
-
-## Mandatory Actions When Bugs Are Found
-
-### Step 1: Fix the Bug
-
-Follow standard bug fix workflow (see foundation `bug_fix_detection.mdc`).
-
-### Step 2: Add Regression Test
-
-**MUST add test that would have caught the bug.**
-
-**Requirements:**
-- Test must fail before fix
-- Test must pass after fix
-- Test must exercise the specific code path that had the bug
-- Test must verify the specific condition that was broken
-
-### Step 3: Analyze Test Coverage Gap
-
-**MUST document why existing tests missed the bug.**
-
-**Required analysis:**
-1. What test coverage existed?
-2. Why did it not catch the bug?
-3. What was wrong with the test approach?
-4. What test patterns were missing?
-
-**Create analysis document:**
-- Location: `docs/reports/{BUG_NAME}_TEST_COVERAGE_GAPS.md` (or repository equivalent)
-- Contents: Detailed analysis of why tests missed the bug
-- Include: Specific test code that would have caught it
-- Include: Root cause analysis (mocking, weak assertions, missing edge cases, etc.)
-
-### Step 4: Strengthen Test Coverage
-
-**MUST add tests that fill the identified gaps.**
-
-**Required new tests:**
-1. **Edge case tests** if bug was in edge case handling
-2. **Integration tests without mocks** if bug was hidden by mocks
-3. **Strong assertion tests** if weak assertions allowed bug to pass
-4. **Foreign key tests** if bug was FK-related
-5. **Database state verification tests** if bug left incorrect state
-6. **Complete workflow tests** if bug was in multi-step process
-
-**Add to appropriate test file** per repository structure (unit, integration, E2E).
-
-### Step 5: Evaluate Foundation Generalization
-
-**MUST assess if learnings apply to other repositories.**
-
-**Questions to answer:**
-1. Is this bug pattern specific to this repo or generic?
-2. Would other repositories benefit from this lesson?
-3. Are the test improvements generic or specific?
-4. Should new rules be added to foundation?
-
-**If 80%+ generic → Generalize to foundation:**
-1. Extract generic principles
-2. Create or update foundation document
-3. Update repository document to reference foundation
-4. Keep repository-specific applications separate
-
-**If mostly specific → Keep in repository:**
-1. Document in repository rules
-2. Reference foundation where applicable
-3. No foundation changes needed
-
-### Step 6: Document Learning
-
-**MUST create learning summary document.**
-
-**Location**: `docs/reports/{BUG_NAME}_LEARNING_SUMMARY.md` (or repository equivalent)
-
-**Contents:**
-- What happened (bug summary)
-- Why tests missed it (root cause)
-- What we learned (principles)
-- Rules created/updated (with links)
-- Impact assessment (before/after)
-- Validation (how future bugs will be caught)
-
-## Constraints
-
-Agents MUST:
-- Add regression test when fixing bugs (never fix without test)
-- Analyze why existing tests missed the bug
-- Document test coverage gaps
-- Add tests to fill identified gaps
-- Evaluate if learnings are generic (80%+ → foundation)
-- Generalize to foundation when appropriate
-- Document learning summary
-- Sync rules to `.claude/rules/` when repository uses setup_cursor_copies
-
-Agents MUST NOT:
-- Fix bugs without adding regression tests
-- Skip gap analysis ("tests just missed it")
-- Skip test coverage improvements
-- Skip foundation generalization evaluation
-- Keep generic learnings siloed in repository
-- Leave learning undocumented
-
-## Related Documents
-
-- Foundation `bug_fix_detection.mdc` — Bug fix workflow
-- Foundation `instruction_documentation.mdc` — Rule creation process
-- Repository testing standards
-- Foundation testing conventions (if present)

package/.claude/rules/checkpoint_management.md

@@ -1,194 +0,0 @@
----
-description: "Load when executing release workflow or updating release status: after a batch completes, mark any checkpoint triggered by that batch as completed in status.md; ensure Checkpoint 2 is completed when all batches done."
-alwaysApply: false
----
-
-<!-- Source: foundation/agent_instructions/cursor_rules/checkpoint_management.mdc -->
-
-# Checkpoint Management Rule
-
-**Reference:** `foundation/development/release_workflow.md` — Checkpoint sections
-
-Configuration is read from `foundation-config.yaml`.
-
-Ensures checkpoints are automatically updated in `status.md` when their trigger batches complete, preventing checkpoints from remaining `pending` after completion criteria are met.
-
-## Checkpoint Trigger Rules
-
-Checkpoints are configured in `manifest.yaml` with `checkpoint_{id}_after_batch` fields:
-
-```yaml
-checkpoints:
-  checkpoint_0.5_after_batch: 0.6 # Review milestone after Batch 0.6
-  checkpoint_1_after_batch: 4 # Mid-release review after Batch 4
-```
-
-**Checkpoint 2 (Pre-Release Sign-Off)** is always triggered when all batches are complete and release status is `ready_for_deployment` or `completed`.
-
-## Automatic Checkpoint Completion
-
-### When a Batch Completes
-
-1. **Check manifest.yaml for checkpoint triggers:**
-
-   - Look for `checkpoint_{id}_after_batch` fields
-   - If current batch ID matches any checkpoint trigger → mark checkpoint as `completed`
-
-2. **Update status.md checkpoint section:**
-
-   - Change checkpoint status from `pending` to `completed`
-   - Add completion notes with:
-     - Batch that triggered completion
-     - Key items completed in that batch (FUs or tasks)
-     - Brief validation summary
-
-3. **Checkpoint 2 completion:**
-   - When all batches complete → automatically mark Checkpoint 2 as `completed`
-   - Add notes: batch completion count, release status, critical item completion status
-
-### Example Checkpoint Update
-
-**Before (Batch 0.6 completes):**
-
-```markdown
-- **Checkpoint 0.5 — Foundation Review**: `pending`
-  - Configured after Batch 0.6 (foundation architecture complete).
-```
-
-**After (automatic update):**
-
-```markdown
-- **Checkpoint 0.5 — Foundation Review**: `completed`
-  - Configured after Batch 0.6 (foundation architecture complete).
-  - Batch 0.6 completed: [Key items] all complete.
-  - Foundation architecture validated.
-```
-
----
-
-## Agent Actions
-
-### During Batch Execution
-
-**After marking a batch as `completed` in status.md:**
-
-1. **Check for checkpoint triggers:**
-
-   ```javascript
-   // Pseudo-code logic
-   const completedBatchId = batch.batch_id;
-   const checkpointTriggers = manifest.checkpoints;
-
-   for (const [checkpointKey, triggerBatch] of Object.entries(
-     checkpointTriggers
-   )) {
-     if (triggerBatch === completedBatchId) {
-       // Mark checkpoint as completed
-       updateCheckpointStatus(checkpointKey, "completed", {
-         batch: completedBatchId,
-         items: batch.items,
-         timestamp: new Date().toISOString(),
-       });
-     }
-   }
-   ```
-
-2. **Update status.md:**
-   - Find checkpoint section
-   - Change status from `pending` to `completed`
-   - Add completion notes
-
-### After All Batches Complete
-
-1. **Check if Checkpoint 2 exists:**
-
-   - Look for "Checkpoint 2 — Pre-Release Sign-Off" in status.md (or similar final checkpoint name)
-
-2. **If exists and still `pending`:**
-   - Mark as `completed`
-   - Add completion notes:
-     - Total batches completed
-     - Release status
-     - Critical item completion count
-
----
-
-## Integration Points
-
-### Release Orchestrator
-
-The release orchestrator script should:
-
-- After each batch completes → check and update checkpoints
-- After all batches complete → ensure Checkpoint 2 is completed
-
-### Manual Batch Updates
-
-When manually updating `status.md` to mark a batch complete:
-- Also check and update any triggered checkpoints
-- Verify checkpoint status matches batch completion state
-
-### Report Generation
-
-Report generation reads checkpoint status from `status.md`:
-
-- If checkpoints are incorrectly `pending` → report will show incorrect metrics
-- Always verify checkpoint status matches batch completion before generating reports
-
----
-
-## Validation Rules
-
-**Before marking release as `ready_for_deployment`:**
-
-1. **Verify all checkpoints are completed:**
-
-   - Checkpoint 0 (Planning) → should be `completed` at start
-   - Checkpoint 0.5 → should be `completed` if trigger batch is complete
-   - Checkpoint 1 → should be `completed` if trigger batch is complete
-   - Checkpoint 2 → should be `completed` if all batches are complete
-
-2. **If any checkpoint is incorrectly `pending`:**
-   - STOP and update checkpoint status
-   - Add completion notes
-   - Then proceed with release status update
-
-## Error Prevention
-
-**Common Issues:**
-
-1. **Checkpoint remains `pending` after batch completes:**
-
-   - **Cause:** Manual batch update without checkpoint check
-   - **Prevention:** Always check checkpoint triggers when updating batch status
-
-2. **Checkpoint marked `completed` before batch completes:**
-
-   - **Cause:** Premature checkpoint update
-   - **Prevention:** Only update checkpoint when batch status is `completed`
-
-3. **Checkpoint 2 not completed:**
-   - **Cause:** Overlooked when all batches complete
-   - **Prevention:** Explicit check after all batches complete
-
----
-
-## Constraints
-
-- Do NOT mark checkpoint as `completed` before trigger batch is `completed`
-- Always add completion notes when updating checkpoint status
-- Always verify checkpoint status matches batch completion state
-- Do NOT skip checkpoint updates - they are required for accurate reporting
-
-## Configuration
-
-Checkpoint management uses paths from `foundation-config.yaml`:
-
-```yaml
-orchestration:
-  release:
-    enabled: true
-    directory: "docs/releases/"  # Or configured path
-    status_file: "status.md"
-    manifest_file: "manifest.yaml"
-```