neotoma 0.3.0 → 0.3.2

package/foundation/.cursor/rules/document_loading_order.mdc

@@ -1,194 +0,0 @@
----
-description: "Load documentation in the correct order to establish context before proceeding. Load when starting work that requires multiple docs or rule files."
-alwaysApply: false
----
-# Document Loading Order Rule
-
-**Reference:** `foundation/conventions/documentation-standards.md` - Documentation standards
-
-## Purpose
-
-Ensures agents load documentation in the correct order to establish proper context before proceeding with work.
-
-## Scope
-
-This document defines:
-- Mandatory loading order for documentation
-- Foundation submodule usage
-- Workflows for AI assistants and human developers
-
-This document does NOT cover:
-- Specific constraints agents must enforce (see `agent_constraints.md`)
-- Risk management and hold points (see `risk_management.md`)
-- Repository-specific document paths (configured in `foundation-config.yaml`)
-
-## Configuration
-
-Configure document loading paths in `foundation-config.yaml`:
-
-```yaml
-agent_instructions:
-  enabled: true
-  location: "docs/foundation/agent_instructions.md"  # Repository-wide agent instructions
-  foundation_docs_path: "docs/foundation/"  # Path to foundation documents
-  cursor_rules:
-    enabled: true
-    location: ".cursor/rules/"
-```
-
-**Document paths are configurable per repository.** Default paths shown above can be customized in `foundation-config.yaml`.
-
-## Mandatory Loading Order
-
-Every AI assistant session MUST load documents in this order:
-
-### 1. Foundation Documents (First)
-
-Load foundation documents from configured foundation docs path FIRST (default: `docs/foundation/`):
-
-**Required foundation documents:**
-- Core philosophy/principles document (e.g., `philosophy.md`, `principles.md`)
-- Core identity document (e.g., `core_identity.md`, `identity.md`)
-- Data models document (if applicable, e.g., `data_models.md`)
-- Architecture document (if applicable, e.g., `architecture.md`, `layered_architecture.md`)
-
-**Why:** These establish the fundamental constraints and boundaries that all other work must respect.
-
-**Configuration:** Set `agent_instructions.foundation_docs_path` in `foundation-config.yaml` to customize the path.
-
-### 2. Foundation Submodule Documents (When Needed)
-
-Load shared foundation processes from `foundation/` submodule when needed:
-
-- `foundation/development/workflow.md` - For git workflow, branching, PRs
-- `foundation/conventions/code-conventions.md` - For code style and naming
-- `foundation/conventions/documentation-standards.md` - For documentation structure
-- `foundation/security/security-rules.md` - For security practices
-- `foundation-config.yaml` - For repository-specific configuration
-
-**When:** Load when working on development workflow, code style, documentation, or security-related tasks.
-
-### 3. Task-Specific Documents
-
-Load task-specific docs based on change type:
-
-- **Architecture changes:** Architecture docs from configured architecture path (default: `docs/architecture/`)
-- **Subsystem work:** Relevant subsystem docs from configured subsystems path (default: `docs/subsystems/`)
-- **Feature work:** Feature specs from configured specs path (default: `docs/specs/` or `docs/feature_units/`)
-- **Release work:** Release plans and status from configured releases path (default: `docs/releases/`)
-- **Documentation work:** Documentation standards from configured conventions path (default: `docs/conventions/`)
-- **Code work:** Code conventions from configured conventions path (default: `docs/conventions/`)
-
-**Configuration:** Document paths can be customized per repository structure.
-
-### 4. Related Context Documents
-
-Load additional context as needed:
-
-- Related subsystem docs
-- Integration guides
-- Testing standards
-- API specifications
-
-## For AI Assistants
-
-**Every session:**
-
-1. Load foundation documents from configured foundation docs path first (see Section 1)
-2. Load foundation submodule docs when relevant (see Section 2)
-3. Reference foundation documents to resolve ambiguities
-4. Validate all outputs against invariants
-5. Stop at hold points for human approval (see `.cursor/rules/foundation-risk_management.md` if exists)
-
-**When uncertain:**
-
-- Default to conservative interpretation
-- Prioritize correctness over convenience
-- Ask for clarification rather than guess
-
-## For Human Developers
-
-**Before starting work:**
-
-1. Read foundation documents from configured foundation docs path (see Section 1)
-2. Read relevant subsystem/docs as indicated by context
-3. Understand project constraints and boundaries
-4. Verify feature fits within project scope
-
-**During implementation:**
-
-- Follow project conventions
-- Write maintainable code
-- Test thoroughly
-- Document all assumptions
-
-**Before committing:**
-
-- **Run security audit** from `foundation/security/pre-commit-audit.sh` (if configured)
-- Verify alignment with project standards
-- Check validation checklists
-- Run full test suite
-- Update docs if patterns changed
-- **Follow commit format** from `foundation/development/workflow.md` (configured in `foundation-config.yaml`)
-
-## Using Foundation Submodule
-
-Repositories using the foundation framework have access to the shared **foundation** submodule (`foundation/`) for development processes and conventions:
-
-### When to Reference Foundation
-
-**Development Workflow:**
-- Creating branches: See `foundation/development/workflow.md` and `foundation/development/branch-strategy.md`
-- Creating worktrees: Use `foundation/development/worktree-setup.sh` (if configured)
-- PR process: Follow `foundation/development/pr-process.md`
-- Commit format: Configured in `foundation-config.yaml` (see `development.commit_format.pattern`)
-
-**Code Conventions:**
-- Code style: See `foundation/conventions/code-conventions.md`
-- Naming patterns: See `foundation/conventions/naming-patterns.yaml`
-- Repository overrides: Check `foundation-config.yaml` for repo-specific settings
-
-**Documentation:**
-- Doc structure: Follow `foundation/conventions/documentation-standards.md`
-- Writing style: Avoid AI-generated patterns, use RFC 2119 language
-- Agent Instructions: Use template from `foundation/agent_instructions/README.md`
-
-**Security:**
-- Pre-commit audit: Run `foundation/security/pre-commit-audit.sh` before commits (if configured)
-- Credential management: See `foundation/security/credential-management.md`
-- Security rules: See `foundation/security/security-rules.md`
-
-**Configuration:**
-- Repository config: `foundation-config.yaml` (repo root)
-- Foundation defaults: `foundation/config/foundation-config.yaml`
-
-### Foundation Submodule vs Repository Foundation Docs
-
-- **`foundation/` submodule**: Shared development processes (workflow, conventions, security) - can be used by multiple repos
-- **Repository foundation docs** (e.g., `docs/foundation/`): Repository-specific foundation (philosophy, architecture, product positioning) - repository only
-
-Both are important:
-- Use `foundation/` for development practices (how to code, commit, review)
-- Use repository foundation docs for repository architecture (what to build, why, constraints)
-
-### Syncing Foundation Updates
-
-When foundation submodule is updated:
-
-```bash
-# Update to latest foundation
-git submodule update --remote foundation
-
-# Or use sync script (if available)
-./foundation/scripts/sync-foundation.sh
-```
-
-See `foundation/README.md` for complete foundation documentation.
-
-## Related Documents
-
-- `foundation/conventions/documentation-standards.md` - Documentation standards
-- `foundation/README.md` - Foundation submodule documentation
-- `foundation-config.yaml` - Repository-specific foundation configuration
-- `.cursor/rules/foundation-risk_management.md` - Risk management and hold points (if exists)
-

package/foundation/.cursor/rules/documentation_rules.mdc

@@ -1,166 +0,0 @@
----
-description: "Create and maintain documentation to minimize context usage while keeping clarity. Load when creating or editing documentation files."
-alwaysApply: false
----
-# 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/foundation/.cursor/rules/downstream_doc_updates.mdc

@@ -1,266 +0,0 @@
----
-description: "When upstream documentation is updated, update all downstream docs that depend on it. Load when editing docs that other docs reference."
-alwaysApply: false
----
-# 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
-
-
-
-
-
-
-
-
-