neotoma 0.3.0 → 0.3.2

package/.claude/rules/documentation_rules.md

@@ -1,169 +0,0 @@
----
-description: "Load when creating or maintaining documentation: minimize context use, reference files instead of inlining, keep rules under 500 lines, follow doc structure and writing style standards."
-alwaysApply: false
----
-
-<!-- Source: foundation/agent_instructions/cursor_rules/documentation_rules.mdc -->
-
-# Documentation Rules
-
-Rules for creating and maintaining documentation files to minimize context window usage while maintaining clarity.
-
-## Core Principles
-
-**Minimize context usage:** Every word, section, and file consumes context. Remove anything that doesn't directly serve the reader's immediate need.
-
-**Single source of truth:** Each concept, rule, or process documented once. Reference, don't duplicate.
-
-**Concise language:** Use the shortest clear phrasing. Prefer direct statements over explanations.
-
-## Content Rules
-
-### Avoid Redundancy
-
-**Within files:**
-- Don't repeat the same rule in multiple sections
-- Don't restate the title in the first paragraph
-- Don't summarize what you're about to say before saying it
-
-**Between files:**
-- Don't duplicate rules across multiple files
-- Reference other files instead of copying content
-- If overlap exists, consolidate into one file and reference it
-
-**Examples:**
-- Bad: "This document defines requirements. The requirements are defined below."
-- Good: "Requirements:"
-
-### Remove Unnecessary Elements
-
-**Don't include:**
-- "Related Documentation" sections (use file structure and naming for discovery)
-- Meta properties (Status, Last Updated, Related) in file headers
-- Separator lines (`---`) unless grouping distinct sections
-- Empty lines between every section (use sparingly)
-- Introductory paragraphs that restate the title
-- "Purpose" sections that repeat the filename
-- Closing summaries that restate what was said
-
-**Do include:**
-- Direct statements of rules or requirements
-- Essential context only
-- Examples when they clarify ambiguity
-
-### Language Conciseness
-
-**Use:**
-- Direct commands: "Do X" not "Agents should do X" or "It is recommended that agents do X"
-- Short phrases: "Required" not "This is a mandatory requirement"
-- Active voice: "Create file" not "File should be created"
-- Lists over paragraphs when possible
-- Specific terms over general ones
-
-**Avoid:**
-- Hedging language: "should", "may", "consider" (use "must" or "do not")
-- Filler phrases: "in order to", "for the purpose of", "it is important to note"
-- Redundant qualifiers: "very important", "absolutely required"
-- Explanatory preambles: "The reason for this is..." (state the rule, not why it exists unless critical)
-
-### Structure
-
-**File organization:**
-- Start with title (no preamble)
-- Use `##` for main sections
-- Use `###` for subsections
-- Use lists for multiple items
-- Group related rules together
-
-**Section naming:**
-- Use action-oriented names: "Creating Files" not "File Creation Process"
-- Keep names short: "Rules" not "Rules and Guidelines"
-- Avoid generic names: "Requirements" not "General Information"
-
-## Formatting Rules
-
-**Minimal formatting:**
-- Use `**bold**` only for emphasis on key terms or mandatory markers
-- Use `*italic*` sparingly
-- Avoid nested formatting
-- Use code blocks only for actual code or file paths
-- Use inline code for file paths, commands, field names
-
-**Lists:**
-- Prefer bullet lists over numbered lists unless sequence matters
-- Use short items (one line when possible)
-- Don't add punctuation to list items unless needed for clarity
-
-## File Creation
-
-**Before creating a new file:**
-1. Check if the content belongs in an existing file
-2. Check if similar content exists elsewhere
-3. Consider if a reference would suffice
-
-**File naming:**
-- Use descriptive, specific names
-- Avoid generic terms: "guide", "manual", "documentation"
-- Prefer action-oriented names: "data-entry-requirements.md" not "data-entry-guide.md"
-
-**File size:**
-- Keep files focused on a single domain or topic
-- If a file grows beyond ~300 lines, consider splitting
-- Prefer multiple focused files over one large file
-
-## Maintenance
-
-**When updating:**
-- Remove outdated content immediately
-- Consolidate duplicate rules
-- Remove sections that no longer apply
-- Update references if files are renamed or merged
-
-**When referencing:**
-- Use file paths, not "see above" or "as mentioned"
-- Reference specific files, not "related documentation"
-- Don't create cross-reference sections
-
-## Examples
-
-**Bad:**
-```markdown
-# Agent Data Entry Requirements
-
-## Purpose
-
-This document defines mandatory requirements for agents when adding, updating, or modifying data records across all data types.
-
-## Introduction
-
-Agents must follow these requirements to ensure data quality and consistency.
-
-## Requirements
-
-### Financial Data Entry
-
-**MANDATORY:** When adding cash flow entries or any financial data records, agents should always include comprehensive details in order to ensure proper categorization and tracking.
-
-**Required Fields:**
-- **Party/Vendor:** Include vendor name, contractor, or party involved (never leave empty)
-- **Location:** Specify property location or relevant address when applicable
-
-## Related Documentation
-
-- `/docs/instructions-index.md` - Central index
-- `/docs/decision-framework-rules.md` - Decision-making framework
-```
-
-**Good:**
-```markdown
-# Agent Data Entry Requirements
-
-## Financial Data Entry
-
-**MANDATORY:** Include comprehensive details for all cash flow entries.
-
-**Required fields:**
-- Party/Vendor: vendor name, contractor, or party (never empty)
-- Location: property location or relevant address when applicable
-```
-

package/.claude/rules/downstream_doc_updates.md

@@ -1,269 +0,0 @@
----
-description: "Load when modifying foundation, architecture, specs, or subsystem docs: identify downstream dependencies via doc_dependencies.yaml, update all downstream docs that restate or depend on the change, run validation script."
-alwaysApply: false
----
-
-<!-- Source: foundation/agent_instructions/cursor_rules/downstream_doc_updates.mdc -->
-
-# Downstream Documentation Update Rule
-
-**Reference:** `foundation/conventions/documentation-standards.md` — Documentation standards
-
-Ensures that when upstream documentation is updated, all downstream documentation that depends on it is also updated to maintain consistency across the documentation tree.
-
-Automated validation via:
-
-- Dependency mapping: `docs/doc_dependencies.yaml` (or configured path) — Explicit upstream→downstream relationships
-- Validation script: `scripts/validate-doc-dependencies.js` (or configured path) — Checks downstream docs for outdated references
-- Pre-commit hook: Automatically validates modified docs before commit
-
-## Configuration
-
-Configure dependency tracking in `foundation-config.yaml`:
-
-```yaml
-tooling:
-  doc_dependencies:
-    enabled: true
-    dependency_map_path: "docs/doc_dependencies.yaml"  # Optional
-    validation_script_path: "scripts/validate-doc-dependencies.js"  # Optional
-```
-
-## Trigger Patterns
-
-When any of the following occur, agents MUST identify and update downstream documentation:
-
-- **Upstream documentation changes:**
-  - Foundation documents modified (`docs/foundation/` or configured path)
-  - Architecture documents updated (`docs/architecture/` or configured path)
-  - Specification changes (`docs/specs/` or configured path)
-  - Subsystem documentation modified (`docs/subsystems/` or configured path)
-  - Standards or conventions updated (`docs/conventions/`, `docs/feature_units/standards/` or configured paths)
-
-- **User explicitly requests downstream updates:**
-  - "update downstream docs"
-  - "sync docs with [upstream change]"
-  - "ensure all docs reflect [change]"
-
-- **Significant changes to:**
-  - Core principles or philosophy
-  - Architectural decisions or patterns
-  - API contracts or specifications
-  - Data models or schemas
-  - Workflow processes or standards
-
-## Documentation Dependency Hierarchy
-
-### Generic Upstream → Downstream Relationships
-
-```
-docs/foundation/ (root)
-  ↓
-docs/architecture/
-docs/specs/
-docs/conventions/
-  ↓
-docs/subsystems/
-docs/feature_units/standards/
-  ↓
-docs/feature_units/completed/
-docs/releases/
-docs/developer/
-docs/integrations/
-  ↓
-README.md
-```
-
-**Key Dependencies:**
-
-1. **Foundation docs** (`docs/foundation/` or configured) → All other docs depend on these
-2. **Architecture docs** (`docs/architecture/` or configured) → Subsystems, feature units, releases
-3. **Specs** (`docs/specs/` or configured) → Feature units, releases, developer docs
-4. **Standards** (`docs/feature_units/standards/` or configured) → Completed feature units, releases
-5. **Subsystems** (`docs/subsystems/` or configured) → Feature units, developer docs, integrations
-6. **All docs** → README.md (via readme_maintenance rule)
-
-**Note:** Customize directory structure per repository. The hierarchy above is a common pattern but should be adapted to your project structure.
-
-## Agent Actions
-
-### Step 1: Identify Upstream Change
-
-When modifying documentation:
-
-1. **Classify the change:**
-   - Foundation change (core identity, philosophy, principles)
-   - Architecture change (system design, layer boundaries)
-   - Specification change (requirements, API specs, feature units)
-   - Subsystem change (components, modules, services)
-   - Standard change (testing, documentation, workflow)
-
-2. **Determine scope of impact:**
-   - Which downstream docs reference this upstream doc?
-   - Which docs restate or depend on this information?
-   - Which docs might contradict if not updated?
-
-### Step 2: Identify Downstream Dependencies
-
-1. **Use dependency map first (if configured):**
-   - Check dependency map file for explicit downstream dependencies
-   - Run validation script if available: `node scripts/validate-doc-dependencies.js [upstream-doc-path]`
-   - Review script output for missing references or broken links
-
-2. **Search for explicit references:**
-   - Links to the modified document
-   - Cross-references in "Related Documents" sections (see format below)
-   - Mentions of concepts from the upstream doc
-
-3. **Identify implicit dependencies:**
-   - Docs that restate information from upstream
-   - Docs that depend on concepts defined upstream
-   - Docs that must align with upstream changes
-
-4. **Check common downstream locations:**
-   - Feature specs (reference architecture, specs, standards)
-   - Release plans (reference specs, features, architecture)
-   - Developer docs (reference architecture, subsystems, standards)
-   - Integration guides (reference subsystems, specs)
-   - README.md (references all major doc categories)
-
-### Step 3: Update Downstream Documentation
-
-For each downstream document:
-
-1. **Review content for outdated information:**
-   - Check if downstream doc restates upstream information
-   - Verify consistency with upstream changes
-   - Identify contradictions or outdated references
-
-2. **Update as needed:**
-   - Update restated information to match upstream
-   - Update references and links
-   - Remove contradictions
-   - Add new information if relevant
-
-3. **Maintain document integrity:**
-   - Preserve document structure and purpose
-   - Keep downstream-specific context intact
-   - Ensure updates don't break document flow
-
-### Step 4: Validate Consistency
-
-Before completing:
-
-1. **Run validation script (if configured):**
-   ```bash
-   node scripts/validate-doc-dependencies.js [modified-upstream-doc-path]
-   ```
-   - Fix any errors (broken links, missing files)
-   - Review warnings (missing explicit references)
-   - Ensure all downstream dependencies are validated
-
-2. **Verify consistency:**
-   - Downstream docs align with upstream changes
-   - No contradictions between docs
-   - Terminology consistent across docs
-
-3. **Check references:**
-   - All links resolve correctly
-   - Cross-references are accurate
-   - Related Documents sections are current (see format below)
-
-4. **Ensure completeness:**
-   - All affected downstream docs identified
-   - All necessary updates made
-   - No critical dependencies missed
-   - Dependency map updated if new relationships discovered
-
-## Common Downstream Update Scenarios
-
-### Scenario 1: Foundation Document Change
-
-**Upstream:** Foundation document modified
-
-**Downstream to check:**
-- Architecture docs (reference foundation)
-- Specs (restate foundation concepts)
-- Feature specs (reference foundation)
-- All subsystem docs (must align with foundation)
-- `README.md` (references foundation)
-
-### Scenario 2: Architecture Change
-
-**Upstream:** Architecture document modified
-
-**Downstream to check:**
-- Subsystem docs (must align with architecture)
-- Feature specs (reference architecture)
-- Release plans (reference architecture)
-- Developer docs (reference architecture)
-- `README.md` (references architecture)
-
-### Scenario 3: Specification Change
-
-**Upstream:** Specification document modified
-
-**Downstream to check:**
-- Architecture docs (reference specs)
-- Feature implementations (implement specs)
-- Release plans (reference specs)
-- Developer docs (reference specs)
-- `README.md` (references specs)
-
-### Scenario 4: Standard Change
-
-**Upstream:** Standard document modified
-
-**Downstream to check:**
-- Feature specs (reference standards)
-- Completed features (must follow standards)
-- Release plans (reference standards)
-- `README.md` (references standards)
-
-### Scenario 5: Subsystem Change
-
-**Upstream:** Subsystem document modified
-
-**Downstream to check:**
-- Architecture docs (reference subsystems)
-- Feature implementations (implement subsystem features)
-- Release plans (reference subsystems)
-- Developer docs (reference subsystems)
-- Integration guides (may reference subsystems)
-- `README.md` (references subsystems)
-
-## Related Documents Format
-
-**Standard format for "Related Documents" sections:**
-
-```markdown
-## Related Documents
-
-- [`docs/path/to/doc.md`](../relative/path/to/doc.md) — Brief description
-- [`docs/another/doc.md`](./relative/path.md) — Brief description
-```
-
-**Requirements:**
-- Use `## Related Documents` heading (level 2)
-- List items with markdown links using backticks
-- Include relative paths (not absolute)
-- Provide brief description after link
-- List upstream dependencies first, then related docs
-
-## Constraints
-
-- Identify downstream dependencies when updating upstream docs
-- Update all downstream docs that restate or depend on upstream changes
-- Verify consistency across documentation tree
-- Do NOT leave contradictions between upstream and downstream docs
-- Do NOT skip downstream updates due to scope
-- Maintain document integrity while updating
-
-
-
-
-
-
-
-
-

package/.claude/rules/env_check.md

@@ -1,55 +0,0 @@
----
-description: "When facing environment variables as a need, always check .env for relevant variables"
-globs: ["**/*"]
-alwaysApply: true
----
-
-<!-- Source: foundation/agent_instructions/cursor_rules/env_check.mdc -->
-
-# Check .env for Relevant Environment Variables
-
-## Purpose
-
-Ensures agents consult the project `.env` (or configured env file) whenever environment variables are relevant to the task, so configuration is accurate and existing variables are reused.
-
-## Scope
-
-This rule covers:
-- Implementing or debugging code that uses environment variables
-- Troubleshooting failures that may be caused by missing or wrong env configuration
-- Documenting or suggesting environment variables
-- Scripts or tooling that depend on env vars
-
-## Trigger Patterns
-
-Agents MUST check `.env` when:
-- Implementing a feature that reads `process.env.*` or equivalent
-- Debugging runtime or startup errors that could be config-related
-- Adding or changing configuration (e.g., API URLs, keys, feature flags)
-- Writing or updating docs that reference env variables
-- User mentions env vars, `.env`, or configuration problems
-
-## Agent Actions
-
-1. **When env variables are needed:**
-   - Read the project `.env` (repo root; see worktree rule for worktrees) to see which variables exist and how they are named.
-   - Prefer reusing existing variable names and patterns (e.g., `DEV_*`, `API_BASE_URL`) instead of introducing new ones without reason.
-   - If adding a new variable, add it to `.env.example` or documented env list; do not commit `.env` (it is gitignored).
-
-2. **When troubleshooting:**
-   - If the issue might be config-related, check `.env` for presence and value of relevant variables before assuming code bugs.
-   - Respect that `.env` may be absent in some environments (e.g., CI); use `.env.example` or docs for required variables.
-
-3. **When documenting:**
-   - When documenting env vars, cross-check with `.env.example` and repository environment docs so names and purpose stay consistent.
-
-## Constraints
-
-- MUST check `.env` (or the env file in use) when implementing or debugging anything that depends on environment variables.
-- MUST NOT commit `.env` or put secrets in versioned files.
-- MUST NOT invent env variable names without checking existing usage in `.env.example` or repository environment documentation.
-
-## Related Documents
-
-- Repository environment documentation — Environment variable management
-- Foundation rule `worktree_env.mdc` — Where env files live and worktree copy behavior