neotoma 0.3.0 → 0.3.2

package/.claude/rules/environment_variables_1password.md

@@ -1,315 +0,0 @@
----
-description: "Load when scripts or config need env vars stored in 1Password: use sync command to load into .env first; scripts read from .env only; add mappings if missing; never fetch from 1Password at runtime."
-alwaysApply: false
----
-
-<!-- Source: foundation/agent_instructions/cursor_rules/environment_variables_1password.mdc -->
-
-# Environment Variables from 1Password Rule
-
-**Reference:** `foundation/agent_instructions/cursor_rules/configuration_management.md` - Configuration management
-
-## Purpose
-
-Ensures agents always fetch environment variables from 1Password when needed, rather than asking users or using placeholders. This applies to all environment variables that exist in 1Password, including credentials, API keys, and configuration values.
-
-## Trigger Patterns
-
-When any of the following occur, agents MUST fetch environment variables from 1Password:
-
-- **Scripts or code require environment variables** that are stored in 1Password
-- **Configuration needs credentials** (API keys, tokens, passwords, etc.)
-- **Setting up integrations** that require authentication (SendGrid, AWS, etc.)
-- **Deploying or configuring services** that need secrets
-- **User explicitly requests** environment variable setup
-- **Environment variables are missing from .env** after sync (check if mapping exists, add if needed)
-
-## Agent Actions
-
-### Step 1: Identify Required Environment Variables
-
-When code or scripts need environment variables:
-
-1. **Identify what's needed:**
-   - Check script/code for environment variable references
-   - Identify which variables are required
-   - Determine if they exist in 1Password
-
-2. **Check if mappings exist:**
-   - Query `env_var_mappings` parquet to see if variables are mapped
-   - If not mapped but exist in 1Password, **proactively add mappings** (see Step 1a)
-
-### Step 1a: Add Missing Mappings (Proactive)
-
-**If a required variable exists in 1Password but is not in mappings:**
-
-1. **Add mapping to env_var_mappings parquet:**
-   - Use MCP parquet `add_record` to add the mapping
-   - Include: `env_var`, `op_reference`, `vault`, `item_name`, `service`, `is_optional`
-   - Format: `op://{vault}/{item_name}/{field_label}`
-
-2. **Example:**
-   ```javascript
-   // Add SENDGRID_API_KEY mapping
-   {
-     "data_type": "env_var_mappings",
-     "record": {
-       "env_var": "SENDGRID_API_KEY",
-       "op_reference": "op://Private/Sendgrid/API key",
-       "vault": "Private",
-       "item_name": "Sendgrid",
-       "service": "SendGrid",
-       "is_optional": false
-     }
-   }
-   ```
-
-3. **After adding mappings, run sync command:**
-   - Run `/sync_env_from_1password` to load new variables into `.env`
-
-### Step 2: Load Environment Variables into .env
-
-**MANDATORY: Use sync command to load variables into .env first:**
-
-1. **Run sync command** (preferred method):
-   ```bash
-   /sync_env_from_1password
-   ```
-   Or via npm:
-   ```bash
-   npm run sync:env
-   ```
-   Or directly:
-   ```bash
-   export ENVIRONMENT=development  # or production (defaults to development)
-   python3 foundation/scripts/op_sync_env_from_1password.py
-   ```
-   - This syncs all mapped variables from 1Password to `.env`
-   - Handles environment-based keys automatically
-   - Preserves unmanaged variables
-   - Creates backup before modification
-
-2. **Verify variables are in .env:**
-   ```bash
-   grep "^VARIABLE_NAME=" .env
-   ```
-
-**For variables not in mappings:**
-
-1. **Add to env_var_mappings first** (if it's a recurring need):
-   - Use MCP parquet `add_record` to add mapping
-   - Then run sync command to load into `.env`
-
-2. **If one-time use only:**
-   - Manually fetch from 1Password and add to `.env`
-   - Or add to mappings for future syncs
-
-### Step 3: Use in Scripts/Code
-
-**In scripts:**
-- **MUST NOT directly integrate with 1Password** - scripts should only read from `.env`
-- **MUST assume variables are already in `.env`** (loaded via sync command)
-- **MUST NOT fetch from 1Password at runtime** - use sync command first
-- **MUST NOT ask users for credentials** - direct them to run sync command instead
-- Read values from `.env` file or environment variables
-
-**In code:**
-- Read from environment variables (loaded from `.env` after sync)
-- Never prompt users for credentials that exist in 1Password
-- Never directly call 1Password CLI from application code
-
-## Examples
-
-### ✅ Correct: Load Variables via Sync Command, Then Use in Script
-
-```bash
-# Step 1: Load variables into .env via sync command
-/sync_env_from_1password
-# or: npm run sync:env
-
-# Step 2: Script reads from .env (no 1Password integration)
-if [ -f .env ]; then
-  source .env  # or use grep to extract specific variables
-  SENDGRID_SENDER_EMAIL="${SENDGRID_SENDER_EMAIL}"
-fi
-```
-
-### ✅ Correct: Script Assumes Variables in .env
-
-```bash
-#!/bin/bash
-# Script reads from .env (variables loaded via sync command)
-if [ -f .env ]; then
-  DATABASE_URL=$(grep "^DATABASE_URL=" .env | cut -d '=' -f2- | sed 's/^"//;s/"$//' | tr -d '\n')
-  SENDGRID_API_KEY=$(grep "^SENDGRID_API_KEY=" .env | cut -d '=' -f2- | sed 's/^"//;s/"$//' | tr -d '\n')
-fi
-```
-
-### ✅ Correct: Agent Runs Sync Command First
-
-```bash
-# Agent action: Run sync command before executing script
-/sync_env_from_1password
-
-# Then run script that uses variables
-./scripts/my_script.sh  # Script reads from .env
-```
-
-### ❌ Incorrect: Direct 1Password Integration in Scripts
-
-```bash
-# WRONG - Script should not directly fetch from 1Password
-SENDGRID_API_KEY=$(op item get "Sendgrid" --vault Private --fields "API key" --format json | python3 -c "...")
-```
-
-### ❌ Incorrect: Ask User for Credentials
-
-```bash
-# WRONG - Don't ask user for values that exist in 1Password
-read -p "Enter SendGrid API key: " API_KEY
-# Instead: Direct user to run /sync_env_from_1password
-```
-
-### ❌ Incorrect: Use Placeholder Values
-
-```bash
-# WRONG - Don't use placeholders when values exist in 1Password
-SENDGRID_SENDER_EMAIL="your-email@example.com"  # Should be in .env after sync
-```
-
-### ❌ Incorrect: Skip Sync Command
-
-```bash
-# WRONG - Don't skip sync command and try to fetch directly
-if [ -z "$API_KEY" ]; then
-  op item get "..."  # Should run /sync_env_from_1password first
-fi
-```
-
-## Integration with Sync Command
-
-**The `/sync_env_from_1password` command** (or `sync_env_from_1password` cursor command) **MUST be run:**
-
-1. **Before running ANY script** that needs environment variables from 1Password
-2. **After updating 1Password** with new credentials
-3. **When setting up** a new environment
-4. **When switching** between development/production
-5. **When variables are missing** from `.env`
-
-**The sync command:**
-- Reads mappings from `env_var_mappings` parquet (via MCP)
-- Fetches values from 1Password using `op` CLI
-- Updates `.env` file with resolved values
-- Preserves unmanaged variables
-- Handles environment-based keys (development/production)
-- Creates backup before modification
-
-**Scripts MUST NOT:**
-- Directly call 1Password CLI (`op` commands)
-- Fetch credentials at runtime from 1Password
-- Integrate 1Password authentication logic
-- Ask users to provide credentials manually
-
-**Scripts MUST:**
-- Read from `.env` file only
-- Assume variables are already loaded via sync command
-- Provide clear error if variable missing (direct user to run sync command)
-
-## Constraints
-
-- **MUST use sync command** (`/sync_env_from_1password`) to load variables into `.env` first
-- **MUST NOT integrate 1Password directly** into scripts - scripts read from `.env` only
-- **MUST NOT ask users** for credentials that are in 1Password - direct them to run sync command
-- **MUST NOT use placeholders** when real values are available in 1Password
-- **MUST NOT fetch from 1Password at runtime** - use sync command before running scripts
-- **MUST add to mappings** if variable will be needed repeatedly (then sync will include it)
-- **MUST assume variables are in `.env`** - scripts should read from `.env`, not 1Password
-
-## When Variables Are Missing
-
-**If variable is not in `.env` after sync:**
-
-1. **Run sync command first:**
-   ```bash
-   /sync_env_from_1password
-   ```
-
-2. **If still missing:**
-   - Check if variable is in `env_var_mappings` parquet
-   - If not, add mapping first, then re-run sync
-   - If mapping exists, verify 1Password item/field exists
-
-3. **If 1Password CLI is not authenticated:**
-   - Prompt user to authenticate: `eval $(op signin)`
-   - Then re-run sync command
-
-**If variable doesn't exist in 1Password:**
-
-1. **Add it to 1Password** first (if it's a credential/secret)
-2. **Add to env_var_mappings** if it will be needed regularly
-3. **Run sync command** to load into `.env`
-
-**Scripts should handle missing variables gracefully:**
-
-```bash
-if [ -z "$REQUIRED_VAR" ]; then
-  echo "❌ REQUIRED_VAR not found in .env"
-  echo "   Run: /sync_env_from_1password"
-  echo "   Or: npm run sync:env"
-  exit 1
-fi
-```
-
-## Related Documents
-
-- `foundation/scripts/op_sync_env_from_1password.py` - Environment sync script
-- `foundation/agent_instructions/cursor_commands/sync_env_from_1password.md` - Sync command documentation
-- `foundation/agent_instructions/cursor_rules/configuration_management.md` - Configuration management
-
-## Agent Instructions
-
-### When to Load This Document
-
-Load this document when:
-- Writing scripts that need environment variables
-- Configuring services that require credentials
-- Setting up integrations
-- User requests environment variable setup
-
-### Required Co-Loaded Documents
-
-- `foundation/agent_instructions/cursor_rules/configuration_management.md` - Configuration management
-- `foundation/agent_instructions/cursor_commands/sync_env_from_1password.md` - Sync command reference
-
-### Constraints Agents Must Enforce
-
-1. **Always run sync command first** (`/sync_env_from_1password`) to load variables into `.env`
-2. **Never integrate 1Password directly** into scripts - scripts read from `.env` only
-3. **Never ask users for credentials** - direct them to run sync command instead
-4. **Never use placeholder values** when real values are available in 1Password
-5. **Never fetch from 1Password at runtime** - use sync command before running scripts
-6. **Add to env_var_mappings** if variable will be needed repeatedly (then sync will include it)
-7. **Scripts assume variables are in `.env`** - provide clear errors if missing, directing to sync command
-
-### Forbidden Patterns
-
-- **Integrating 1Password CLI directly into scripts** (`op` commands in scripts)
-- **Fetching credentials at runtime from 1Password** (should be in `.env` after sync)
-- **Asking users for credentials** that exist in 1Password (direct to sync command instead)
-- **Using placeholder values** when real values are available in 1Password
-- **Skipping sync command** and trying to fetch directly from 1Password
-- **Hardcoding credentials** in scripts or code
-- **Assuming users will manually set environment variables** (use sync command)
-
-### Validation Checklist
-
-- [ ] Checked env_var_mappings for required variables (added mappings if missing)
-- [ ] Ran sync command (`/sync_env_from_1password`) before executing scripts
-- [ ] Verified required variables are in `.env` after sync
-- [ ] Scripts read from `.env` only (no direct 1Password integration)
-- [ ] No `op` CLI commands in scripts (1Password integration removed)
-- [ ] No user prompts for credentials (added mappings and ran sync instead)
-- [ ] No placeholder values used when real values are available
-- [ ] Added to env_var_mappings if variable will be needed repeatedly
-- [ ] Scripts provide clear errors if variables missing (direct to sync command)
-- [ ] Ran `scripts/setup_claude_instructions.sh` if foundation rules/commands were updated

package/.claude/rules/environment_variables_env_file.md

@@ -1,124 +0,0 @@
----
-description: "Load when code/scripts need env vars, or troubleshooting config: check .env first before assuming unset; use values from .env; do not ask user for values that should be in .env."
-alwaysApply: false
----
-
-<!-- Source: foundation/agent_instructions/cursor_rules/environment_variables_env_file.mdc -->
-
-
-# Environment Variables from .env File Rule
-
-**Reference:** `foundation/agent_instructions/cursor_rules/configuration_management.mdc` - Configuration management
-
-## Purpose
-
-Ensures agents always check the `.env` file for environment variables before assuming they are unset or asking users for values. The `.env` file is the primary source of environment variable configuration in repositories.
-
-## Trigger Patterns
-
-When any of the following occur, agents MUST check the `.env` file first:
-
-- **Environment variable is referenced** in code, scripts, or configuration
-- **Environment variable appears to be unset** (empty value from `process.env` or `$VAR`)
-- **User mentions an environment variable** that needs to be used
-- **Scripts require environment variables** for execution
-- **Configuration depends on environment variables**
-
-## Agent Actions
-
-### Step 1: Check .env File First
-
-When an environment variable is needed:
-
-1. **Check if `.env` file exists:**
-   ```bash
-   test -f .env && echo ".env exists" || echo ".env not found"
-   ```
-
-2. **Read the variable from `.env`:**
-   ```bash
-   grep "^VARIABLE_NAME=" .env
-   # Or with value extraction:
-   grep "^VARIABLE_NAME=" .env | cut -d'=' -f2 | tr -d '"'
-   ```
-
-3. **For multiple variables or complex parsing:**
-   ```bash
-   # Use grep with pattern matching for multiple variable names
-   grep -E "^DATA_DIR=|^ALTERNATE_DATA_DIR=" .env
-   ```
-
-### Step 2: Use the Value from .env
-
-1. **Extract the value** from `.env` file
-2. **Use the value directly** in commands or scripts
-3. **Do NOT assume the variable is unset** just because it's not in the current shell environment
-
-### Step 3: Handle Missing Variables
-
-If the variable is not in `.env`:
-
-1. **Check `.env.example`** for expected variables
-2. **Check repository documentation** for setup instructions
-3. **Check if variable should be synced from 1Password** (see `foundation/agent_instructions/cursor_rules/environment_variables_1password.mdc` if applicable)
-4. **Only then ask the user** if the variable is truly missing
-
-## Examples
-
-### ✅ Correct: Check .env First
-
-```
-User: "Use DATA_DIR to create symlink"
-Agent:
-1. Checks .env: grep "^DATA_DIR=" .env
-2. Finds: DATA_DIR="/path/to/data"
-3. Uses the value from .env to create symlink
-```
-
-### ✅ Correct: Extract Value from .env
-
-```bash
-# Extract DATA_DIR from .env
-DATA_DIR=$(grep -E "^DATA_DIR=" .env | cut -d'=' -f2 | tr -d '"')
-# Use the value
-ln -sfn "$DATA_DIR" data
-```
-
-### ❌ Incorrect: Assume Variable is Unset
-
-```
-User: "Use DATA_DIR"
-Agent: "DATA_DIR is not set" # WRONG - should check .env first
-```
-
-### ❌ Incorrect: Ask User Before Checking
-
-```
-User: "What's the value of DATA_DIR?"
-Agent: "What should DATA_DIR be set to?" # WRONG - should check .env first
-```
-
-## Constraints
-
-- **MUST check `.env` file first** before assuming an environment variable is unset
-- **MUST use values from `.env`** when they exist
-- **MUST NOT assume** environment variables are unset just because they're not in the current shell
-- **MUST handle quoted values** in `.env` (remove quotes when extracting)
-- **MUST check `.env.example`** if variable is missing from `.env`
-- **MUST check repository-specific documentation** for environment variable setup if variable is missing
-
-## Integration with Other Rules
-
-This rule works in conjunction with:
-
-- **`foundation/agent_instructions/cursor_rules/environment_variables_1password.mdc`** - For syncing variables from 1Password to `.env` (if applicable)
-- **`foundation/agent_instructions/cursor_rules/configuration_management.mdc`** - Configuration file management
-- **Repository-specific environment documentation** - For setup instructions
-
-## Notes
-
-- The `.env` file is typically gitignored and may not be readable via `read_file` tool
-- Use terminal commands (`grep`, `cut`, etc.) to read `.env` file
-- Values in `.env` may be quoted (single or double quotes) - handle accordingly
-- Some variables may have multiple names (e.g., `DATA_DIR` and `ALTERNATE_DATA_DIR`) - check both
-- Repository-specific environment variable management may have additional rules or documentation

package/.claude/rules/feature_unit_detection.md

@@ -1,132 +0,0 @@
----
-description: "Load when user mentions create feature, new feature, add feature, feature unit, or feature ID: check if FU exists; if not, confirm then run feature unit creation workflow with required docs."
-alwaysApply: false
----
-
-<!-- Source: foundation/agent_instructions/cursor_rules/feature_unit_detection.mdc -->
-
-# Feature Unit Creation Detection Rule
-
-**Reference:** `foundation/development/feature_unit_workflow.md` — Complete workflow
-
-This is a foundation rule. Configuration is read from `foundation-config.yaml`.
-
-## Trigger Patterns
-
-When a user mentions any of the following patterns, automatically detect feature unit creation intent:
-
-- "create feature"
-- "new feature"
-- "add feature"
-- "implement feature"
-- "feature unit" or configured abbreviation
-- Feature Unit ID matching configured pattern (check `feature_units.id_pattern` in foundation-config)
-- Feature descriptions that imply new work (e.g., "we need to add X", "implement Y functionality")
-- Planning discussions about new functionality
-
-## Agent Actions
-
-### Step 1: Detection and Confirmation
-
-If context suggests feature unit creation (mentions "feature", feature IDs, feature descriptions, etc.):
-
-1. **Load configuration:**
-   - Read `foundation-config.yaml` to get feature unit settings
-   - Extract `feature_units.directory`, `feature_units.id_pattern`
-   - Check if feature units are enabled
-
-2. **Extract feature information** from context:
-   - Feature Unit ID (if mentioned, validate against configured pattern)
-   - Feature name or description
-   - Priority hints (P0/P1/P2/P3)
-   - Scope hints (what functionality is mentioned)
-
-3. **Check if feature unit already exists:**
-   - Look for `{configured_directory}/completed/{feature_id}/`
-   - Look for `{configured_directory}/in_progress/{feature_id}/`
-   - Look for repository-specific FU inventory (if configured)
-
-4. **If feature unit exists:**
-   - Inform user: "Feature Unit {feature_id} already exists. Status: {status}"
-   - Ask: "Do you want to modify it or create a new one? (modify/new)"
-
-5. **If feature unit does NOT exist:**
-   - **Ask for confirmation:**
-     ```
-     I see you're requesting a new Feature Unit. Should I create a Feature Unit spec 
-     in `{configured_directory}/in_progress/{feature_id}/` following the Feature Unit 
-     creation workflow? (yes/no)
-     ```
-   
-   If feature ID was detected, include it in the path.
-
-6. **If feature ID not detected:**
-   - Show configured ID pattern: "What Feature Unit ID should I use? (format: {configured_pattern}, e.g., FU-2025-01-001)"
-   - Wait for user input before proceeding
-
-7. **Exception handling:**
-   - If user says "no" → do not proceed with feature unit creation
-   - If user says "just a spec document" → create spec document instead
-
-### Step 2: Execute Feature Unit Creation Workflow
-
-**If user confirms (yes) and feature_id is provided:**
-
-1. **Load required documents:**
-   - `foundation/development/feature_unit_workflow.md` (primary workflow)
-   - `foundation/agent_instructions/cursor_commands/create_feature_unit.md` (command implementation, or `.claude/skills/foundation_create_feature_unit.md` if symlinked)
-   - `foundation/development/templates/feature_unit_spec_template.md` (spec template)
-   - `foundation/development/templates/manifest_template_simple.yaml` or `manifest_template_extended.yaml` (manifest template, based on config)
-   - Repository-specific FU inventory (if configured)
-
-2. **Follow the Feature Unit creation workflow:**
-   - Start at Step 0 (Checkpoint 0) — Spec Creation
-   - Check if spec exists (completed or in_progress)
-   - If spec exists: validate completeness, proceed if complete
-   - If spec does NOT exist: **STOP and prompt user** interactively for all required spec details (questions based on configuration)
-   - Generate complete spec and manifest from user input
-   - **Validate dependencies** — REJECT if dependencies not implemented (if validation enabled)
-   - Create file structure (spec, manifest, test directories)
-   - Do NOT implement code yet — only scaffolds
-
-3. **Alignment Check (Spec vs Mental Model):**
-   - After drafting the spec, produce a concise summary covering:
-     - Problem it solves and why it exists
-     - What is explicitly in scope and out of scope
-     - Which modules/subsystems it will touch (if architecture tracking enabled)
-     - Critical invariants or constraints
-   - Present summary to user and ask:
-     - "Does this accurately capture what you want this Feature Unit to do? (yes/no)"
-     - "What feels off, missing, or over-scoped compared to your intent?"
-   - Incorporate corrections immediately and re-summarize if changes are substantial
-   - Do NOT proceed until user confirms spec summary matches their mental model
-
-4. **Create file structure:**
-   ```
-   {configured_directory}/in_progress/{feature_id}/
-     ├── {feature_id}_spec.md
-     └── manifest.yaml
-   
-   tests/unit/features/{feature_id}/
-   tests/integration/features/{feature_id}/
-   tests/e2e/features/{feature_id}/  (if e2e tests required by config)
-   tests/regression/features/{feature_id}/
-   ```
-
-## Constraints
-
-- Do NOT proceed without user confirmation - always ask before creating feature unit specs
-- Do NOT proceed without feature_id - always require explicit feature ID
-- Do NOT skip dependency validation - always check dependencies if validation enabled in config
-- Do NOT create incomplete specs - always collect all required information
-- Always get user approval at configured checkpoints
-- Always validate dependencies if enabled in configuration
-
-## Integration with Commands
-
-This rule complements the explicit `/create_feature_unit` command:
-- **Rule-based detection:** Triggers automatically when patterns are detected
-- **Explicit command:** User can call `/create_feature_unit` directly with feature_id
-
-Both paths lead to the same workflow execution.
-

package/.claude/rules/file_naming.md

@@ -1,34 +0,0 @@
----
-description: "Load when creating or renaming files or folders: use underscores (snake_case) for all names; use when referencing paths in documentation; symlinks may use foundation_ prefix."
-alwaysApply: false
----
-
-<!-- Source: foundation/agent_instructions/cursor_rules/file_naming.mdc -->
-
-# File and Folder Naming Convention
-
-All filenames and folder names must use underscores (snake_case), not kebab-case (dashes).
-
-## Format
-
-**Files:**
-- Correct: `create_feature_unit.md`, `setup_symlinks.md`, `run_feature_workflow.md`
-- Incorrect: `create-feature-unit.md`, `setup-symlinks.md`, `run-feature-workflow.md`
-
-**Folders:**
-- Correct: `cursor_rules/`, `feature_units/`, `agent_instructions/`, `repo_adapters/`
-- Incorrect: `cursor-rules/`, `feature-units/`, `agent-instructions/`, `repo-adapters/` (use underscores: `cursor_rules/`, `feature_units/`, `agent_instructions/`, `repo_adapters/`)
-
-## When Creating or Renaming
-
-1. Use underscores (snake_case) for all filenames and folder names
-2. Use underscores when referencing files or folders in documentation
-3. Symlinks automatically use `foundation_` prefix (e.g., `foundation_create_feature_unit.md`)
-
-## Migration
-
-If existing files or folders use kebab-case:
-
-1. Rename from `command-name.md` to `command_name.md` or `folder-name/` to `folder_name/`
-2. Update references in `foundation_config.yaml`, documentation files, and scripts
-3. Run `setup_cursor_rules.sh` to update symlinks