neotoma 0.3.0 → 0.3.2

package/.claude/rules/agent_constraints.md

@@ -1,201 +0,0 @@
----
-description: "Load when validating work or before completing: enforce architectural boundaries, determinism, immutability, project principles; no credentials in instructions; run validation checklist."
-alwaysApply: false
----
-
-<!-- Source: foundation/agent_instructions/cursor_rules/agent_constraints.mdc -->
-
-# Agent Constraints Rule
-
-**Reference:** `foundation/conventions/documentation-standards.md` - Documentation standards
-
-## Purpose
-
-Ensures agents enforce all absolute constraints, forbidden patterns, and validation requirements when working on the repository.
-
-## Scope
-
-This document defines:
-- Absolute constraints that agents MUST enforce
-- Project positioning constraints (if configured)
-- Constraints agents must enforce
-- Communication constraints
-- Forbidden patterns
-- Validation checklist
-
-This document does NOT cover:
-- Repository-specific constraints (configured in `foundation-config.yaml`)
-- Risk management and hold points (see `risk_management.md`)
-- Document loading order (see `document_loading_order.md`)
-
-## Configuration
-
-Configure project-specific constraints in `foundation-config.yaml`:
-
-```yaml
-agent_instructions:
-  enabled: true
-  constraints: []  # Repository-specific constraints
-    # Example:
-    # - "Never violate architectural boundaries"
-    # - "Always follow schema-first principles"
-    # - "Enforce immutability for core data"
-  validation_checklist:
-    enabled: true
-    custom_checks: []  # Repository-specific validation checks
-```
-
-**Constraints are configurable per repository.** Default constraints shown below can be customized or extended in `foundation-config.yaml`.
-
-## Absolute Constraints
-
-Agents MUST enforce these constraints at all times (customize in `foundation-config.yaml`):
-
-1. **Never violate architectural boundaries** (respect layer boundaries, no cross-layer violations)
-2. **Never introduce nondeterminism** (no random IDs, no unstable logic, deterministic outputs)
-3. **Never generate features outside project scope** (stay within defined boundaries)
-4. **Always follow project principles** (schema-first, type-driven, or project-specific patterns)
-5. **Enforce data integrity** (immutability where required, proper validation)
-6. **Enforce safety and explicit control** (user approval where required, no implicit actions)
-7. **Always output validated artifacts** (code, specs, docs must pass validation)
-8. **Follow project positioning** (when creating marketing/content, follow project differentiators if configured)
-
-## Project Positioning Constraints (Optional)
-
-**If configured:** All release planning, marketing content, and feature positioning MUST validate project differentiators.
-
-Configure project differentiators in `foundation-config.yaml`:
-
-```yaml
-project:
-  differentiators: []  # Project-specific differentiators
-    # Example:
-    # - "privacy-first"
-    # - "deterministic"
-    # - "cross-platform"
-  positioning_framework: "docs/private/competitive/positioning_framework.md"  # Optional
-```
-
-### When Creating Release Plans (If Differentiators Configured)
-
-1. **Explicitly validate project differentiators**: Release must validate configured differentiators
-2. **Avoid feature-only releases**: Don't ship features without validating differentiators
-3. **Include acceptance criteria**: Release acceptance criteria must validate differentiators
-4. **Reference framework**: Link to positioning framework (if configured) in release plans
-
-### When Creating Marketing Content (If Differentiators Configured)
-
-1. **Lead with project differentiators**, not features alone
-2. **Contextualize features** as enabled by differentiators
-3. **Avoid feature-only positioning** (competitors may develop similar features)
-4. **Emphasize structural barriers** that prevent competitors from pursuing same path
-5. **Validate messaging**: All marketing messaging must emphasize differentiators first
-
-### When Creating Content, Documentation, or Positioning (If Differentiators Configured)
-
-1. **Lead with project differentiators**, not features alone
-2. **Contextualize features** as enabled by differentiators
-3. **Avoid feature-only positioning**
-4. **Emphasize structural barriers**
-5. **Reference framework** when appropriate (if configured)
-
-## Constraints Agents Must Enforce
-
-**Base constraints (always apply):**
-
-1. **Architectural boundaries:** MUST NOT violate layer boundaries or architectural constraints (configured per repository)
-2. **Determinism:** MUST NOT introduce randomness or nondeterministic logic (no random IDs, no unstable sorting, no `Date.now()` in business logic unless required)
-3. **Data integrity:** MUST NOT modify immutable data after storage (respect immutability requirements)
-4. **Project principles:** MUST follow project-specific principles (schema-first, type-driven, or as configured)
-5. **Explicit control:** MUST NOT implement automatic/implicit actions without user approval (respect explicit control requirements)
-6. **Provenance:** MUST trace all outputs to source (source file, rule, timestamp, or as configured)
-7. **Data integrity:** MUST maintain data consistency (no orphans, no cycles, transactional writes where required)
-8. **Privacy:** MUST NOT log sensitive data (PII, credentials, or as configured - only IDs/logs as allowed)
-9. **Security:** MUST NOT include credentials (API keys, tokens, service keys) in agent instructions, conversation text, or commit messages. Credentials MUST be injected via secure mechanisms (e.g., Cursor Cloud Agents Secrets) and agents MUST verify their availability via environment variable checks, not export commands with credential values
-
-**Repository-specific constraints:** Add custom constraints in `foundation-config.yaml` under `agent_instructions.constraints`.
-
-## Forbidden Patterns
-
-**Base forbidden patterns (always apply):**
-
-- Violating architectural boundaries (implementing logic outside defined layer boundaries)
-- Introducing nondeterminism (random IDs, unstable sorting, `Date.now()` in business logic unless required)
-- Generating features outside project scope (features not aligned with project goals)
-- Breaking immutability (modifying immutable data after initial storage)
-- Inferring beyond extraction (creating data not present in source, inferring relationships without explicit rules)
-- Schema mutations (changing assigned types after creation, unless allowed)
-- Synthetic data (guessing missing information, hallucinating fields)
-- Upward dependencies (lower layers calling higher layers, violating layer boundaries)
-- Non-transactional writes (data writes must be atomic where required)
-- Including credentials in agent instructions (no API keys, tokens, or service keys in prompt text, conversation messages, or code comments; use secure injection mechanisms like Cursor Secrets)
-- Storing documentation files in repo root (all documentation MUST be in appropriate `docs/` subdirectories)
-
-**Repository-specific forbidden patterns:** Add custom patterns in `foundation-config.yaml` under `agent_instructions.forbidden_patterns`.
-
-## Communication Constraints
-
-**Prohibitions:**
-- No emojis
-- No filler language
-- No hype
-- No soft asks
-- No conversational transitions
-- No call-to-action appendices
-- No questions, offers, suggestions, or motivational content
-- No tone matching, emotional softening, or user sentiment modulation
-
-**Assumptions:**
-- User possesses high cognitive acuity, though may have reduced verbal fluency
-
-**Execution rules:**
-- Use blunt, directive phrasing for cognitive restructuring
-- Suppress all engagement-optimizing or corporate-aligned behaviors:
-  - User satisfaction scores
-  - Conversational flow tagging
-  - Continuation bias
-  - Sentiment uplift
-- Avoid mirroring the user's tone, mood, or diction
-- Communicate strictly to the deep cognitive tier—beyond surface-level language
-
-**Response protocol:**
-- Deliver the requested or relevant information only
-- Terminate immediately after delivery—no transitions, no conclusions
-
-**End goal:**
-- User independence and cognitive restoration
-- Model obsolescence via user self-sufficiency
-
-## Validation Checklist
-
-Before completing any work, verify:
-
-**Base checks (always apply):**
-
-- [ ] Change respects architectural boundaries (no layer violations)
-- [ ] No nondeterministic logic introduced (no randomness, no unstable sorts)
-- [ ] Immutability preserved (immutable data not modified)
-- [ ] Schema changes are additive only (no breaking changes, no column removal)
-- [ ] Project principles followed (schema-first, type-driven, or as configured)
-- [ ] Data integrity maintained (no orphans, no cycles, transactional writes where required)
-- [ ] Privacy preserved (no sensitive data in logs, only IDs/logs as allowed)
-- [ ] Provenance maintained (all outputs trace to source)
-- [ ] Consistency model correct (as required per subsystem/component)
-- [ ] Security: No credentials included in agent instructions, conversation text, or code (use secure injection mechanisms)
-- [ ] Documentation location: No documentation files stored in repo root (all docs in `docs/` subdirectories)
-- [ ] Tests cover all new paths (unit, integration, E2E as appropriate)
-- [ ] Documentation updated to reflect changes
-- [ ] Downstream documentation updated if upstream docs changed
-- [ ] README.md updated if documentation changes affect user-facing information
-- [ ] Feature fits within project scope
-- [ ] No violations of MUST/MUST NOT lists
-- [ ] Project differentiators validated (if configured and if release planning or marketing content)
-
-**Repository-specific checks:** Add custom checks in `foundation-config.yaml` under `agent_instructions.validation_checklist.custom_checks`.
-
-## Related Documents
-
-- `foundation/conventions/documentation-standards.md` - Documentation standards
-- `foundation-config.yaml` - Repository-specific configuration
-- Repository foundation docs (e.g., `docs/foundation/philosophy.md`) - Core philosophy and architectural invariants
-- Repository architecture docs (e.g., `docs/architecture/architecture.md`) - System architecture

package/.claude/rules/agent_instructions_sync_rules.md

@@ -1,100 +0,0 @@
----
-description: "MCP/CLI instruction parity: when either mcp/instructions.md or cli_agent_instructions.md changes, apply equivalent change to the other."
-globs: ["docs/developer/mcp/instructions.md", "docs/developer/cli_agent_instructions.md"]
----
-
-<!-- Source: docs/developer/agent_instructions_sync_rules.mdc -->
-
-
-# Agent Instructions Sync Rule
-
-## Purpose
-
-Ensures behavioral instructions stay in sync across the two agent instruction files. When either file is updated, the equivalent change must be applied to the other.
-
-## Scope
-
-The two files governed by this rule:
-
-- `docs/developer/mcp/instructions.md` — loaded at runtime by `getMcpInteractionInstructions()` in `src/server.ts`; sent verbatim to MCP clients
-- `docs/developer/cli_agent_instructions.md` — source of truth for CLI agent rules; applied to `.claude/rules/neotoma_cli.mdc`, `.claude/rules/`, and `.codex/` by `neotoma cli-instructions check`
-
-This rule does NOT cover:
-- The auto-injected active-env section in `.claude/rules/neotoma_cli.mdc` (managed by CLI session startup)
-- Per-tool descriptions in `docs/developer/mcp/tool_descriptions.yaml`
-- Format differences between the two files (the MCP file uses a plain-text code block; the CLI file uses markdown sections)
-
-## Trigger Patterns
-
-Apply this rule whenever:
-- Any behavioral instruction is added, changed, or removed in either file
-- A new category of behavior is introduced (e.g. new store pattern, new retrieval pattern, new relationship type)
-- Wording of an existing rule is corrected or clarified in one file
-
-## Behavioral Sections That Must Stay in Parity
-
-Each behavioral rule exists in both files with transport-appropriate wording. The following behaviors must be equivalent in both:
-
-| Behavior | MCP anchor | CLI anchor |
-|---|---|---|
-| Chat persistence (MANDATORY) | `Chat (one call):` line | `MANDATORY in chat` bullet |
-| Entity shapes (conversation, agent_message) | `Chat (one call):` line | `MANDATORY in chat` bullet |
-| Stable turn identity (`turn_key`) | `Chat (one call):` line | `MANDATORY in chat` bullet |
-| Observation history / branch overwriting | `Chat details:` line | `Chat details` bullet |
-| Reverted turns (SUPERSEDES) | `Chat details:` line | `Chat details` bullet |
-| Attachments | `Chat details:` line | `Chat details` bullet |
-| Screenshot/image (extract and store) | `Screenshot/image:` line | `Screenshot/image:` bullet |
-| Do not mention storage in thoughts | `Do not mention...` line | `Do not mention` bullet |
-| Store-first rule (external tools) | `Other MCPs:` line | `External tool data` bullet |
-| Proactive retrieval (before final response) | `Proactive retrieval:` line | `Proactive retrieval` bullet |
-| Retrieval guardrails and answer grounding | `Retrieval guardrails:` / `Answer grounding:` lines | `Retrieval guardrails and answer grounding` bullet |
-| User identity | `User identity:` line | `User identity` bullet |
-| Entity extraction | `Extract and store...` line | `Extract and store` bullet |
-| Tasks | `Tasks:` line | `Tasks` bullet |
-| Entity type discovery | `Entity types:` line | `Entity types` bullet |
-| Conventions (pre-check, structured/unstructured path, summary) | `Conventions:` line | `Conventions` bullet |
-| Relationship fallback | `Fallback if relationships...` line | `Relationship creation` section |
-
-## Agent Actions
-
-### When modifying either file
-
-1. **Identify the changed behavior** — which category in the table above does it belong to?
-2. **Locate the equivalent section in the other file** — use the anchor column in the table
-3. **Apply the equivalent change** — reword for the transport (MCP tool calls vs CLI commands) but preserve the behavioral intent exactly
-4. **Verify both files are updated before completing the task**
-
-### Wording conventions
-
-The MCP file is a dense plain-text code block (one instruction per line). The CLI file uses structured markdown with transport-branched wording (`**MCP:** ... **CLI:** ...`). Translate between them:
-
-- MCP action names (`store_structured`, `create_relationship`) → CLI equivalents (`neotoma --servers=start store --json='...'`, `neotoma --servers=start relationships create ...`)
-- MCP retrieval actions (`retrieve_entity_by_identifier`, `retrieve_entities`, `list_timeline_events`, `retrieve_related_entities`, `retrieve_graph_neighborhood`, `list_observations`) → CLI retrieval equivalents (`neotoma --servers=start entities search/list`, timeline/event query commands, `relationships list`, `observations list`)
-- MCP `list_entity_types` → CLI `neotoma --servers=start schemas list --search <keyword>`
-- MCP `npm_check_update` → CLI `neotoma --servers=start --help` / update notifier
-- Inline `relationships: [...]` in MCP store → separate `relationships create` call in CLI
-
-### Files to update
-
-When `docs/developer/mcp/instructions.md` changes:
-- Update `docs/developer/cli_agent_instructions.md` (source of truth for CLI)
-- The `.claude/rules/neotoma_cli.mdc` Rule section is regenerated from the source doc on next CLI session start; if an immediate update is needed, edit `.claude/rules/neotoma_cli.mdc` directly as well
-
-When `docs/developer/cli_agent_instructions.md` changes:
-- Update `docs/developer/mcp/instructions.md`
-- Update `.claude/rules/neotoma_cli.mdc` Rule section directly (same content as source doc)
-
-## Constraints
-
-- MUST update both files when behavioral instructions change in either one
-- MUST NOT change the behavioral intent when translating between transports — only the commands differ
-- MUST NOT add CLI-specific operational sections (e.g. `--servers=start` protocol, `--json=` syntax warning, active-env block) to `mcp/instructions.md`
-- MUST NOT add MCP-specific internals (e.g. `source_index`/`target_index` for inline relationships, `file_content+mime_type` parameters) to the CLI file beyond what is needed for behavioral equivalence
-- MUST verify both files are updated before marking the task complete
-
-## Related Documents
-
-- `docs/developer/mcp/instructions.md` — MCP instruction source
-- `docs/developer/cli_agent_instructions.md` — CLI instruction source
-- `.claude/rules/neotoma_cli.mdc` — applied CLI rule file (auto-updated by CLI session startup)
-- `docs/developer/agent_cli_configuration.md` — CLI/MCP strategy overview

package/.claude/rules/agent_test_execution.md

@@ -1,358 +0,0 @@
----
-description: "Load after implementing code changes or before marking work complete: run type-check, lint, tests, integration tests; fix all failures before proceeding; retry after fixes."
-alwaysApply: false
----
-
-<!-- Source: foundation/agent_instructions/cursor_rules/agent_test_execution.mdc -->
-
-# Agent Test Execution Rules
-
-**Reference:** Testing standards documentation (repository-specific)
-
-## Purpose
-
-Ensures agents automatically run tests after implementing code changes and fix any failures before proceeding. This prevents bugs from being discovered only during manual testing.
-
-## Scope
-
-This document covers:
-- Mandatory test execution after code changes
-- Test execution commands and workflows
-- Failure handling and remediation
-- Test result verification
-
-This document does NOT cover:
-- Test quality standards (see repository test quality rules)
-- Test writing patterns (see repository testing standards)
-- Test-first workflow (see `test_first_workflow.mdc`)
-
-## Trigger Patterns
-
-Agents MUST run tests immediately after:
-
-- Implementing new features or functions
-- Modifying existing code
-- Adding or updating tests
-- Changing database schemas or migrations
-- Updating API endpoints or contracts
-- Modifying UI components
-- Before marking any implementation as complete
-
-## Mandatory Test Execution
-
-### Step 1: Run Relevant Test Suite
-
-After ANY code change, agents MUST run the appropriate test suite:
-
-**For backend/domain changes:**
-```bash
-# Type check first
-npm run type-check
-
-# Run unit tests
-npm test
-
-# Run integration tests
-npm run test:integration
-```
-
-**For frontend/UI changes:**
-```bash
-# Type check
-npm run type-check
-
-# Run unit tests
-npm test
-
-# Run E2E tests (Playwright)
-npm run test:e2e
-```
-
-**For database/schema changes:**
-```bash
-# Run migrations
-npm run migrate
-
-# Run integration tests (includes DB operations)
-npm run test:integration
-
-# Check schema advisors (if available)
-npm run check:advisors
-```
-
-**For all changes:**
-```bash
-# Lint check
-npm run lint
-```
-
-### Step 2: Verify Test Results
-
-After running tests, agents MUST:
-
-1. **Check exit codes:** All test commands must exit with code 0
-2. **Review test output:** Verify all tests passed (not just "some tests passed")
-3. **Check coverage:** Verify coverage meets requirements (if coverage check is enabled)
-4. **Review failures:** If any tests fail, identify root cause
-
-### Step 3: Fix Failing Tests
-
-If tests fail, agents MUST:
-
-1. **STOP all work immediately** — Do not proceed with other tasks
-2. **Read test failure messages** — Understand what failed and why
-3. **Fix the failing tests** — Either fix the code or fix the test (if test is wrong)
-4. **Re-run tests** — Verify fixes work
-5. **Repeat until all tests pass** — Do not mark implementation complete until all tests pass
-6. **Always retry after fixes** — After fixing any failing test, immediately re-run the test suite to verify the fix worked
-
-### Step 3a: Fix Migration Issues Automatically
-
-**MANDATORY:** When database migrations fail (e.g., during local database setup), agents MUST automatically resolve the issues:
-
-1. **Identify the root cause:**
-   - Missing base tables
-   - Missing dependencies (foreign key references)
-   - Duplicate migration timestamps
-   - Syntax errors in migrations
-
-2. **Fix immediately:**
-   - Create seed migration for base tables if missing
-   - Fix duplicate migration timestamps (rename to unique timestamps)
-   - Make migrations conditional if they depend on tables that may not exist
-   - Fix syntax errors in migration SQL
-
-3. **Re-run migrations:**
-   - After fixes, immediately re-run migration command
-   - Verify all migrations apply successfully
-   - Do not proceed until migrations complete without errors
-
-4. **Document fixes:**
-   - Note what was fixed and why
-   - Update migration files with proper conditional logic
-   - Ensure seed migration creates all required base tables
-
-### Step 4: Document Test Results
-
-Agents MUST document test execution in status updates:
-
-```markdown
-## Test Execution Results
-
-- Type check: ✅ Passed
-- Unit tests: ✅ Passed (45/45)
-- Integration tests: ✅ Passed (12/12)
-- E2E tests: ✅ Passed (8/8)
-- Lint: ✅ Passed
-- Coverage: ✅ 87% (meets requirement)
-```
-
-## Test Execution Commands
-
-### Standard Commands
-
-| Command | Purpose | When to Run |
-|---------|---------|-------------|
-| `npm run type-check` | TypeScript compilation check | Always (before tests) |
-| `npm test` | Unit tests | After code changes |
-| `npm run test:integration` | Integration tests | After backend/DB changes |
-| `npm run test:e2e` | E2E tests (Playwright, headless) | After UI/frontend changes |
-| `npm run test:e2e:headed` | E2E tests with visible browser | When visually debugging UI tests |
-| `npm run lint` | Code style check | Always |
-| `npm run test:coverage` | Coverage report | Before marking complete |
-| `npm run migrate` | Database migrations | After schema changes |
-| `npm run check:advisors` | Schema validation | After migrations (if available) |
-
-### Coverage Requirements
-
-When running coverage checks, verify:
-
-- **Domain logic:** >85% lines, >85% branches, 100% critical paths
-- **Application layer:** >80% lines, >80% branches, 100% critical paths
-- **UI components:** >75% lines, >75% branches
-
-See repository testing standards for complete coverage requirements.
-
-## Failure Behavior
-
-### If Tests Fail
-
-**MANDATORY:** Agents MUST NOT proceed until all tests pass.
-
-1. **Stop immediately** — Do not continue with other tasks
-2. **Analyze failure** — Read error messages, stack traces, test output
-3. **Fix root cause** — Fix the code or test (whichever is wrong)
-4. **Re-run tests** — Verify fix works
-5. **Document fix** — Note what was fixed and why
-
-### If Type Check Fails
-
-**MANDATORY:** Fix type errors before running tests.
-
-1. Run `npm run type-check` to see all type errors
-2. Fix type errors (mismatched interfaces, incorrect types, etc.)
-3. Re-run type check until it passes
-4. Then run tests
-
-### If Lint Fails
-
-**MANDATORY:** Fix lint errors (warnings are acceptable but should be reviewed).
-
-1. Run `npm run lint` to see all lint errors
-2. Fix lint errors (code style, unused variables, etc.)
-3. Re-run lint until it passes
-4. Then run tests
-
-### If Coverage Fails
-
-**MANDATORY:** Add missing tests to meet coverage requirements.
-
-1. Run `npm run test:coverage` to see coverage gaps
-2. Identify uncovered code paths
-3. Add tests for uncovered paths
-4. Re-run coverage check until requirements are met
-
-## Integration with Feature Unit Workflow
-
-When implementing Feature Units (if repository uses feature units):
-
-1. **After each implementation step:**
-   - Run relevant tests
-   - Fix any failures
-   - Verify tests pass
-
-2. **Before marking FU complete:**
-   - Run full test suite
-   - Verify all tests pass
-   - Check coverage meets requirements
-   - Document test results in status file
-
-3. **In status updates:**
-   ```json
-   {
-     "tests": {
-       "unit": { "passed": true, "count": 45 },
-       "integration": { "passed": true, "count": 12 },
-       "e2e": { "passed": true, "count": 8 },
-       "coverage": { "lines": 87, "branches": 85 }
-     }
-   }
-   ```
-
-## Constraints
-
-Agents MUST:
-- Run tests after EVERY code change
-- **ALWAYS fix failing tests and retry** — When encountering failing tests, immediately fix them and re-run the test suite to verify the fix
-- Verify all tests pass before marking implementation complete
-- Document test results in status updates
-- Run type check and lint before tests
-- **Retry tests after fixes** — After fixing any failing test, immediately re-run the test suite to confirm the fix worked
-
-Agents MUST NOT:
-- Skip test execution to save time
-- Mark implementation complete if tests fail
-- Proceed with other tasks while tests are failing
-- Assume tests will pass without running them
-- Defer test execution to "later"
-- **Leave failing tests unfixed** — All failing tests must be fixed and verified before proceeding
-
-## Examples
-
-### ✅ Correct: Run Tests After Implementation
-
-```typescript
-// Agent implements feature
-export function newFeature(data: Data): Result {
-  // Implementation
-}
-
-// Agent immediately runs tests
-// Command: npm test
-// Result: ✅ All tests passed
-
-// Agent marks implementation complete
-```
-
-### ❌ Incorrect: Skip Test Execution
-
-```typescript
-// Agent implements feature
-export function newFeature(data: Data): Result {
-  // Implementation
-}
-
-// Agent marks implementation complete WITHOUT running tests
-// Result: Bugs discovered during manual testing
-```
-
-### ✅ Correct: Fix Tests Before Proceeding
-
-```typescript
-// Agent runs tests
-// Result: ❌ 2 tests failed
-
-// Agent stops work, fixes failing tests
-// Agent re-runs tests
-// Result: ✅ All tests passed
-
-// Agent marks implementation complete
-```
-
-### ❌ Incorrect: Proceed Despite Test Failures
-
-```typescript
-// Agent runs tests
-// Result: ❌ 2 tests failed
-
-// Agent marks implementation complete anyway
-// Result: Bugs in production
-```
-
-## Related Documents
-
-- Repository testing standards documentation
-- Repository test quality enforcement rules
-- `test_first_workflow.mdc` — Test-first workflow
-- Repository UI test requirements (if applicable)
-- Repository feature unit execution workflow (if applicable)
-
-## Agent Instructions
-
-### When to Load This Document
-
-Load this document when:
-- Implementing new features or code changes
-- Reviewing agent test execution behavior
-- Setting up automated test workflows
-
-### Required Co-Loaded Documents
-
-- Repository testing standards
-- Repository test quality enforcement rules
-
-### Constraints Agents Must Enforce
-
-1. **MANDATORY test execution** after every code change
-2. **MANDATORY test fixes** before proceeding if tests fail
-3. **MANDATORY test verification** before marking implementation complete
-4. **MANDATORY test documentation** in status updates
-
-### Forbidden Patterns
-
-- Skipping test execution
-- Marking implementation complete with failing tests
-- Proceeding with other tasks while tests fail
-- Assuming tests pass without running them
-- Deferring test execution
-
-### Validation Checklist
-
-Before marking any implementation complete:
-- [ ] Type check passed (`npm run type-check`)
-- [ ] Lint passed (`npm run lint`)
-- [ ] Unit tests passed (`npm test`)
-- [ ] Integration tests passed (`npm run test:integration`) — if backend/DB changes
-- [ ] E2E tests passed (`npm run test:e2e`) — if UI changes
-- [ ] Coverage meets requirements (`npm run test:coverage`) — if enabled
-- [ ] Test results documented in status update