neotoma 0.3.0 → 0.3.2

package/docs/developer/shared_components_submodule_setup.md

@@ -1,273 +0,0 @@
-# Shared UI Components Submodule Setup
-
-This document describes how to set up and use the shared UI components as a git submodule.
-
-## Overview
-
-The shared UI components (`shared-ui-components`) are maintained as a separate git repository and included in both ateles and neotoma as submodules. This allows:
-
-- Single source of truth for shared components
-- Version control across projects
-- Independent development and releases
-- Easy updates across all consuming projects
-
-## Repository Structure
-
-```
-react-components/
-├── components/
-│   ├── ui/              # Base UI components (sidebar, breadcrumb, button)
-│   ├── Layout.jsx       # Configurable layout component
-│   ├── AppSidebar.jsx   # Configurable sidebar navigation
-│   └── ErrorBoundary.jsx # Error boundary component
-├── lib/
-│   └── utils.js         # Utility functions (cn helper)
-├── README.md
-├── package.json
-└── .gitignore
-```
-
-## Initial Setup
-
-### Step 1: Create GitHub Repository
-
-1. Go to https://github.com/new
-2. Repository name: `react-components`
-3. Description: "Shared React UI components for ateles and neotoma"
-4. Set to Private (if needed)
-5. **Do NOT** initialize with README, .gitignore, or license
-6. Click "Create repository"
-
-### Step 2: Push React Components Repository
-
-The repository is already set up at `~/repos/react-components`. Push it to GitHub:
-
-```bash
-cd ~/repos/react-components
-
-# Add remote (replace with your actual repo URL)
-git remote add origin git@github.com:markmhendrickson/react-components.git
-
-# Push to remote
-git push -u origin main
-```
-
-The repository includes:
-- GitHub Actions CI workflows (type-check, lint, build)
-- TypeScript configuration
-- Proper package.json for npm publishing
-- Complete component library structure
-
-### Step 3: Remove from Ateles Parent Repo
-
-```bash
-cd /Users/markmhendrickson/repos/ateles
-
-# Remove the shared directory from git tracking (keep files)
-git rm -r --cached execution/website/shared
-
-# Commit the removal
-git commit -m "Remove shared directory (converting to submodule)"
-```
-
-### Step 4: Add as Submodule to Ateles
-
-```bash
-cd /Users/markmhendrickson/repos/ateles
-
-# Remove existing shared directory from git (keep files if needed)
-git rm -r --cached execution/website/shared 2>/dev/null || true
-rm -rf execution/website/shared
-
-# Add submodule
-git submodule add git@github.com:markmhendrickson/react-components.git execution/website/shared
-
-# Commit the submodule addition
-git add .gitmodules execution/website/shared
-git commit -m "Add react-components as submodule"
-```
-
-### Step 5: Add as Submodule to Neotoma
-
-```bash
-cd /Users/markmhendrickson/repos/neotoma
-
-# Add submodule
-git submodule add git@github.com:markmhendrickson/react-components.git frontend/src/shared
-
-# Commit the submodule addition
-git add .gitmodules frontend/src/shared
-git commit -m "Add react-components as submodule"
-```
-
-**Or use the setup script:**
-
-```bash
-cd /Users/markmhendrickson/repos/neotoma
-./scripts/complete_submodule_setup.sh git@github.com:markmhendrickson/react-components.git
-```
-
-### Step 6: Update Vite Configuration
-
-**In Neotoma (`frontend/vite.config.ts`):**
-
-```typescript
-resolve: {
-  alias: {
-    "@": path.resolve(__dirname, "./src"),
-    "@shared": path.resolve(__dirname, "./src/shared"), // Add this
-  },
-},
-```
-
-**In Ateles websites (`vite.config.js`):**
-
-```javascript
-resolve: {
-  alias: {
-    '@shared': path.resolve(__dirname, '../shared'),
-  },
-},
-```
-
-## Using the Submodule
-
-### Cloning a Repository with Submodules
-
-When cloning a repository that uses submodules:
-
-```bash
-# Clone with submodules
-git clone --recurse-submodules <repository-url>
-
-# Or if already cloned, initialize submodules
-git submodule update --init --recursive
-```
-
-### Updating Submodule to Latest Version
-
-```bash
-cd <repository-root>
-
-# Update submodule to latest commit
-cd frontend/src/shared  # or execution/website/shared in ateles
-git pull origin main
-cd ../..
-
-# Commit the submodule update
-git add frontend/src/shared
-git commit -m "Update shared-ui-components submodule"
-```
-
-### Updating Submodule to Specific Version
-
-```bash
-cd frontend/src/shared  # or execution/website/shared in ateles
-
-# Checkout specific commit or tag
-git checkout <commit-hash>
-# or
-git checkout v1.0.0  # if using tags
-
-cd ../..
-git add frontend/src/shared
-git commit -m "Pin shared-ui-components to v1.0.0"
-```
-
-### Making Changes to Shared Components
-
-1. **Make changes in the submodule:**
-
-```bash
-cd frontend/src/shared  # or execution/website/shared in ateles
-
-# Make your changes
-# ... edit files ...
-
-# Commit in submodule
-git add .
-git commit -m "Add new feature to Layout component"
-git push origin main
-```
-
-2. **Update parent repository to use new version:**
-
-```bash
-cd <repository-root>
-
-# Update submodule reference
-cd frontend/src/shared
-git pull origin main
-cd ../..
-
-# Commit the update
-git add frontend/src/shared
-git commit -m "Update shared-ui-components: Add new feature"
-```
-
-## Workflow Best Practices
-
-### Development Workflow
-
-1. **For shared component changes:**
-   - Work directly in the submodule directory
-   - Test in one project first
-   - Commit and push to shared repository
-   - Update other projects to use new version
-
-2. **For project-specific changes:**
-   - Don't modify shared components directly
-   - Create project-specific wrappers or extensions
-   - Consider contributing changes back to shared if generally useful
-
-### Versioning Strategy
-
-- Use git tags for stable releases: `v1.0.0`, `v1.1.0`, etc.
-- Pin submodules to specific tags for production
-- Use `main` branch for development/testing
-
-### Troubleshooting
-
-**Submodule shows as modified when it shouldn't:**
-
-```bash
-# This usually means the submodule is on a different commit
-cd frontend/src/shared
-git status  # Check what's different
-git checkout main  # Reset to tracked commit
-```
-
-**Submodule is empty after clone:**
-
-```bash
-# Initialize and update submodules
-git submodule update --init --recursive
-```
-
-**Need to remove submodule:**
-
-```bash
-# Remove submodule
-git submodule deinit -f frontend/src/shared
-git rm -f frontend/src/shared
-rm -rf .git/modules/frontend/src/shared
-git commit -m "Remove react-components submodule"
-```
-
-## Migration from Current Setup
-
-If you're migrating from the current setup (components copied in each repo):
-
-1. Follow steps 1-6 above to set up submodule
-2. Update imports in your code:
-   - Change `@/components/Layout` → `@shared/components/Layout`
-   - Change `@/components/ErrorBoundary` → `@shared/components/ErrorBoundary`
-   - etc.
-3. Remove old copied components
-4. Test thoroughly
-5. Commit changes
-
-## Related Documentation
-
-- [Git Submodules Documentation](https://git-scm.com/book/en/v2/Git-Tools-Submodules)
-- [Shared Components README](../../../frontend/src/shared/README.md) (after submodule is added)

package/docs/developer/spec_compliance_validation_system.md

@@ -1,261 +0,0 @@
-# Spec Compliance Validation System
-
-## Problem Statement
-
-Feature Unit FU-100 was marked "complete" but was missing required schema validation and field partitioning logic. The release process lacked automated checks to verify implementation matches spec requirements.
-
-## Solution Overview
-
-Add a mandatory **Spec Compliance Validation** step that:
-
-1. Extracts requirements from FU specs (MUST/MUST NOT/SHALL statements)
-2. Logs implementation decisions during build
-3. Automatically checks code/schema against requirements
-4. Generates compliance reports with gaps
-5. Blocks completion until all requirements are met or explicitly deferred
-
-## Architecture
-
-```mermaid
-flowchart TD
-    A[FU Implementation Complete] --> B[Extract Requirements from Spec]
-    B --> C[Generate Implementation Decision Log]
-    C --> D[Run Automated Compliance Checks]
-    D --> E{Gaps Found?}
-    E -->|Yes| F[Generate Compliance Report]
-    F --> G[Present Gaps to User]
-    G --> H{User Action}
-    H -->|Fix| I[Implement Missing Requirements]
-    H -->|Defer| J[Document Deferral in Decision Log]
-    H -->|Update Spec| K[Update Spec First]
-    I --> D
-    J --> L{User Approval}
-    K --> D
-    L -->|Approved| M[Mark FU Complete]
-    E -->|No| M
-    M --> N[Continue Release Process]
-```
-
-
-
-## Implementation Steps
-
-### 1. Create Requirement Extraction Module
-
-**File:** `scripts/validate_spec_compliance.js`**Functions:**
-
-- `extractRequirements(specPath)`: Parse spec markdown for MUST/MUST NOT/SHALL/MUST IMPLEMENT statements
-- Returns structured requirement objects with:
-                                                                                                                                - `text`: Full requirement text
-                                                                                                                                - `section`: Section heading where found
-                                                                                                                                - `lineNumber`: Line number in spec
-                                                                                                                                - `type`: `must` | `must_not` | `shall` | `required`
-                                                                                                                                - `category`: `implementation` | `database` | `validation` | `testing`
-
-**Implementation:**
-
-- Use regex patterns to find requirement statements
-- Parse markdown headings for section context
-- Track line numbers for traceability
-
-### 2. Create Implementation Decision Logger
-
-**File:** `scripts/validate_spec_compliance.js` (continued)**Functions:**
-
-- `generateImplementationLog(fuId, requirements, outputPath)`: Create decision log template
-- `logDecision(decisionLogPath, requirement, decision)`: Append decision to log
-
-**Decision Log Format:**
-
-```markdown
-## Implementation Decisions
-
-### Decision 1: [Requirement Summary]
-**Requirement:** [Full requirement text]
-**Location:** Section X.Y.Z, line N
-**Implementation approach:** [What was implemented]
-**Files changed:** [List files]
-**Code references:** [Line numbers and functions]
-**Verification:** [How requirement was verified]
-**Status:** ✅ Implemented | ❌ Not Implemented | ⚠️ Partial
-```
-
-
-
-### 3. Create Automated Compliance Checks
-
-**File:** `scripts/validate_spec_compliance.js` (continued)**Check Types:**a. **Code Existence Checks:**
-
-                                                                                                                                                                                                - Function existence: `grep -r "functionName" src/`
-                                                                                                                                                                                                - Import existence: `grep -r "import.*module" src/`
-                                                                                                                                                                                                - Pattern matching: `grep -r "pattern" src/`
-
-b. **Database Schema Checks:**
-
-                                                                                                                                                                                                - Column existence: `grep -r "column_name" migrations/ src/`
-                                                                                                                                                                                                - Table existence: Similar pattern
-                                                                                                                                                                                                - Index existence: Similar pattern
-
-c. **Integration Checks:**
-
-                                                                                                                                                                                                - Service call verification: Check function calls in code
-                                                                                                                                                                                                - Flow verification: Trace execution paths
-
-d. **Validation Logic Checks:**
-
-                                                                                                                                                                                                - Validate functions called: Check if validation functions are invoked
-                                                                                                                                                                                                - Error handling: Check for required error handling
-
-**Function:**
-
-- `runComplianceChecks(fuId, requirements, implementationLog)`: Execute all checks
-- Returns structured results with:
-                                                                                                                                - `requirement`: Requirement object
-                                                                                                                                - `status`: `pass` | `fail` | `partial`
-                                                                                                                                - `evidence`: Code/file references proving implementation
-                                                                                                                                - `gap`: Description of missing implementation
-
-### 4. Create Compliance Report Generator
-
-**File:** `scripts/validate_spec_compliance.js` (continued)**Function:**
-
-- `generateComplianceReport(fuId, checkResults, outputPath)`: Generate markdown report
-
-**Report Format:**
-
-```markdown
-## FU-XXX Compliance Report
-
-### Requirements Status
-| Requirement | Location | Status | Evidence | Gap |
-|------------|----------|--------|----------|-----|
-| [Requirement text] | Section X | ✅ Pass | [Code refs] | - |
-| [Requirement text] | Section Y | ❌ Fail | - | [Gap description] |
-
-### Implementation Gaps
-1. **Critical Gap:** [Gap title]
-            - **Requirement:** [Section reference]
-            - **Current:** [What exists now]
-            - **Required:** [What's needed]
-            - **Files to modify:** [File list]
-```
-
-
-
-### 5. Integrate into Release Orchestrator
-
-**File:** `scripts/release_orchestrator.js`**Changes:**
-
-- Add `validateFUSpecCompliance(fuId, releaseId)` function
-- Call before marking FU as complete in batch processing
-- Block FU completion if gaps found (unless explicitly deferred with approval)
-
-**Integration point:**
-
-- After batch tests pass, before updating `status.completed_fus`
-- Exit with error if critical gaps found
-
-### 6. Update Release Workflow Documentation
-
-**File:** `docs/feature_units/standards/release_workflow.md`**Changes:**
-
-- Add **Step 3.6: Feature Unit Spec Compliance Validation** section
-- Insert between Step 3 (integration tests) and Step 3.5 (architectural completeness)
-- Document process flow, critical rules, and integration points
-
-### 7. Update Final Review Command
-
-**File:** `.cursor/commands/final_review.md`**Changes:**
-
-- Add spec compliance validation as prerequisite
-- Require compliance report generation before presenting review
-- Include compliance status in review summary
-- Block approval if gaps exist
-
-### 8. Create Compliance Check Patterns Library
-
-**File:** `scripts/spec_compliance_patterns.js`**Purpose:** Define common check patterns for reuse across FUs**Patterns:**
-
-- `checkFunctionExists(functionName, filePattern)`
-- `checkDatabaseColumn(columnName, tableName)`
-- `checkImportExists(moduleName, filePattern)`
-- `checkServiceCall(serviceName, functionName, callerPattern)`
-- `checkValidationLogic(validationType, location)`
-
-### 9. Add Compliance Report Storage
-
-**Directory Structure:**
-
-```javascript
-docs/releases/vX.Y.Z/
-  ├── compliance_reports/
-  │   ├── FU-100_compliance.md
-  │   └── FU-101_compliance.md
-  └── implementation_logs/
-      ├── FU-100_implementation_log.md
-      └── FU-101_implementation_log.md
-```
-
-
-
-### 10. Update Status Tracking
-
-**File:** `docs/releases/vX.Y.Z/status.md`**Changes:**
-
-- Add compliance report links to FU status entries
-- Track compliance validation status per FU
-- Include in release summary
-
-## Implementation Files
-
-### New Files
-
-1. `scripts/validate_spec_compliance.js` - Main validation script
-2. `scripts/spec_compliance_patterns.js` - Reusable check patterns
-3. `docs/feature_units/standards/spec_compliance_validation.md` - Detailed process documentation
-
-### Modified Files
-
-1. `scripts/release_orchestrator.js` - Add compliance validation call
-2. `docs/feature_units/standards/release_workflow.md` - Add Step 3.6
-3. `.cursor/commands/final_review.md` - Add compliance check requirement
-
-## Validation Rules
-
-**Critical Rules:**
-
-- NO FU can be marked "complete" without passing spec compliance validation
-- All implementation decisions MUST be logged before validation
-- All gaps MUST be resolved OR explicitly deferred with user approval
-- Deferred requirements MUST be tracked in decision log for future work
-
-**Check Categories:**
-
-1. **Implementation:** Functions, classes, modules exist
-2. **Database:** Tables, columns, indexes exist
-3. **Integration:** Service calls, flows connected
-4. **Validation:** Validation logic present
-5. **Testing:** Required tests exist
-
-## Testing Strategy
-
-1. **Unit tests** for requirement extraction (parse various spec formats)
-2. **Unit tests** for compliance checks (mock file system, verify patterns)
-3. **Integration test** with FU-100 spec (should catch known gaps)
-4. **Integration test** with FU-101 spec (should pass if complete)
-
-## Rollout Plan
-
-1. Implement validation script and patterns
-2. Test with FU-100 (should catch gaps)
-3. Test with FU-101 (should pass)
-4. Integrate into release orchestrator
-5. Update documentation
-6. Apply to next release cycle
-
-## Success Criteria
-
-- FU-100 compliance check catches missing `extraction_metadata` column
-- FU-100 compliance check catches missing `partitionFields()` function
-- Compliance reports generated for all FUs in release
-- Release blocked if critical gaps found

package/docs/developer/test_coverage_gap_analysis_plan.md

@@ -1,36 +0,0 @@
-name: Test Coverage Gap Analysis
-overview: Create a comprehensive test coverage gap analysis document for v0.1.0 release that identifies missing implementations, test coverage gaps, error case gaps, and edge case gaps to guide test improvements.
-todos:
-  - id: create_gap_analysis
-    content: Create comprehensive test coverage gap analysis document for v0.1.0
-    status: pending
-  - id: update_release_workflow_step0
-    content: Add test coverage requirements to Step 0 (Release Planning) in release_workflow.md
-    status: pending
-    dependencies:
-      - create_gap_analysis
-  - id: update_release_workflow_step1
-    content: Add test coverage review to Step 1 (Execute FU Batches) in release_workflow.md
-    status: pending
-    dependencies:
-      - create_gap_analysis
-  - id: update_release_workflow_step4
-    content: Add test coverage validation to Step 4 (Checkpoint 2) in release_workflow.md
-    status: pending
-    dependencies:
-      - create_gap_analysis
-  - id: update_release_workflow_constraints
-    content: Add test coverage constraints and forbidden patterns to release_workflow.md
-    status: pending
-    dependencies:
-      - create_gap_analysis
-  - id: update_release_workflow_manifest
-    content: Add test coverage template to Release Manifest Format section in release_workflow.md
-    status: pending
-    dependencies:
-      - create_gap_analysis
-  - id: update_release_workflow_examples
-    content: Update example release execution sections with test coverage steps in release_workflow.md
-    status: pending
-    dependencies:
-      - create_gap_analysis