neotoma 0.3.0 → 0.3.2

package/docs/feature_units/standards/error_protocol.md

@@ -1,60 +0,0 @@
-# Feature Unit Error Protocol
-*(Error Classification and Remediation)*
-## Error Classes
-### Class 1: Specification Errors
-**When:** Spec incomplete or incorrect before implementation.
-**Examples:**
-- Missing required sections in spec
-- Contradicts foundational docs
-- Invariants not documented
-**Remediation:**
-1. Update spec
-2. Re-review
-3. Proceed with implementation
-### Class 2: Implementation Errors
-**When:** Code doesn't match spec or violates invariants.
-**Examples:**
-- Nondeterministic extraction
-- Missing error handling
-- RLS policy not applied
-- Tests incomplete
-**Remediation:**
-1. Fix code to match spec
-2. Add/fix tests
-3. Re-review
-4. Regression test
-### Class 3: Production Errors
-**When:** Feature deployed but causes issues in production.
-**Examples:**
-- Performance degradation
-- Error rate spike
-- Data corruption
-**Remediation:**
-1. Rollback immediately
-2. Root cause analysis
-3. Fix + add regression tests
-4. Re-deploy with enhanced monitoring
-## Regression Test Requirements
-After any Class 2 or Class 3 error:
-**MUST add regression test that:**
-1. Reproduces the bug
-2. Verifies the fix
-3. Runs in CI forever
-**Example:**
-```typescript
-test('regression: entity ID generation must be deterministic', () => {
-  // Bug: entity IDs were random UUIDs
-  const id1 = generateEntityId('company', 'Acme Corp');
-  const id2 = generateEntityId('company', 'Acme Corp');
-  
-  // Fix: now hash-based
-  expect(id1).toBe(id2);
-});
-```
-## Agent Instructions
-Load when debugging Feature Unit errors or classifying failures.
-Required co-loaded: `docs/feature_units/standards/execution_instructions.md`, `docs/subsystems/errors.md`
-Constraints:
-- MUST classify all errors as Class 1/2/3
-- MUST add regression tests for Class 2/3
-- MUST document root cause

package/docs/feature_units/standards/execution_instructions.md

@@ -1,87 +0,0 @@
-# Feature Unit Execution Instructions
-## Feature Unit Lifecycle
-```mermaid
-%%{init: {'theme':'neutral'}}%%
-flowchart TD
-    Spec[Write Spec] --> Manifest[Create Manifest]
-    Manifest --> Review1[Review Spec + Manifest]
-    Review1 -->|Approved| Plan[Plan Implementation]
-    Review1 -->|Changes| Spec
-    Plan --> Implement[Implement Code]
-    Implement --> Tests[Write Tests]
-    Tests --> Docs[Update Docs]
-    Docs --> Review2[Code Review]
-    Review2 -->|Changes| Implement
-    Review2 -->|Approved| Deploy[Deploy]
-    Deploy --> Monitor[Monitor]
-    Monitor -->|Issues| Rollback[Rollback]
-    Monitor -->|Success| Complete[Complete]
-    style Spec fill:#e1f5ff
-    style Complete fill:#e6ffe6
-    style Rollback fill:#ffe6e6
-```
-## Implementation Order
-1. **Load Documentation**
-   - `docs/NEOTOMA_MANIFEST.md`
-   - Relevant subsystem docs from context index
-   - `docs/conventions/agent_test_execution_rules.mdc` (MANDATORY)
-   - `docs/conventions/test_first_workflow_rules.mdc` (MANDATORY)
-2. **Implement Domain Logic**
-   - Write deterministic extraction/entity resolution
-   - **Write unit tests FIRST or alongside** (see test-first workflow)
-   - **Run unit tests immediately** after each function (`npm test`)
-   - **Fix any failing tests** before proceeding
-3. **Implement Application Logic**
-   - Wire up domain services
-   - Handle errors, emit events
-   - **Write integration tests FIRST or alongside**
-   - **Run integration tests immediately** (`npm run test:integration`)
-   - **Fix any failing tests** before proceeding
-4. **Implement UI (if applicable)**
-   - Build components per spec
-   - Add accessibility (keyboard, ARIA)
-   - Add i18n strings
-   - **Write Playwright E2E tests FIRST or alongside** (see UI test requirements)
-   - **Run E2E tests immediately** (`npm run test:e2e`)
-   - **Fix any failing tests** before proceeding
-5. **Final Test Verification**
-   - **Run full test suite:**
-     - Type check: `npm run type-check`
-     - Lint: `npm run lint`
-     - Unit tests: `npm test`
-     - Integration tests: `npm run test:integration`
-     - E2E tests: `npm run test:e2e` (if UI changes)
-   - **Verify all tests pass** before proceeding
-   - **Check coverage** meets requirements (`npm run test:coverage`)
-6. **Documentation**
-   - Update subsystem docs if patterns changed
-   - Add examples
-7. **Review and Deploy**
-   - Human review per checklist
-   - Deploy with monitoring
-   - Watch key metrics
-## Safety Classification
-| Risk Level | Approval Required       | Testing Required   | Monitoring       |
-| ---------- | ----------------------- | ------------------ | ---------------- |
-| **Low**    | 1 reviewer              | Unit + integration | Standard         |
-| **Medium** | 2 reviewers             | + E2E tests        | Enhanced         |
-| **High**   | Tech lead + 2 reviewers | + Load tests       | Real-time alerts |
-See `docs/private/governance/risk_classification.md` for classification rules.
-## Agent Instructions
-Load when implementing a Feature Unit or understanding execution flow.
-**For creating NEW Feature Units:** See `docs/feature_units/standards/creating_feature_units.md` for complete workflow with interactive checkpoints.
-**For implementing existing Feature Units:** Use this document after spec and prototype are approved.
-Required co-loaded:
-- `docs/feature_units/standards/feature_unit_spec.md` (spec template)
-- `docs/feature_units/standards/error_protocol.md` (error handling)
-- `docs/feature_units/standards/creating_feature_units.md` (creation workflow, if creating new FU)
-Constraints:
-- MUST have complete spec before coding (see creation workflow)
-- MUST have prototype approved (if UI changes) before implementation
-- MUST follow implementation order (this document)
-- **MANDATORY: MUST run tests after EVERY code change** (see `docs/conventions/agent_test_execution_rules.mdc`)
-- **MANDATORY: MUST write tests FIRST or alongside implementation** (see `docs/conventions/test_first_workflow_rules.mdc`)
-- **MANDATORY: MUST fix failing tests before proceeding** (do not mark complete with failing tests)
-- **MANDATORY: MUST run full test suite before marking FU complete**
-- MUST write tests (unit, integration, E2E as applicable)
-- MUST update docs if patterns change

package/docs/feature_units/standards/feature_unit_spec.md

@@ -1,325 +0,0 @@
-# Feature Unit Specification Standard
-## 1. What is a Feature Unit?
-A **Feature Unit** is a complete, self-contained unit of functionality consisting of:
-1. **Spec Document** (this file format)
-2. **Manifest** (YAML, see `manifest_template.yaml`)
-3. **Implementation** (code changes)
-4. **Tests** (unit, integration, E2E as appropriate)
-5. **Documentation Updates** (if introducing new patterns)
-**Feature Units MUST be:**
-- **Atomic:** Complete a single logical feature or fix
-- **Testable:** Include comprehensive tests
-- **Documented:** Fully specified before coding
-- **Reviewable:** Complete context for human review
-- **Deterministic:** Reproducible outcomes
-## 2. Feature Unit Specification Template
-### Feature Unit ID and Metadata
-```markdown
-# Feature Unit: [FU-YYYY-MM-NNN] [Feature Name]
-**Status:** Draft | In Progress | Review | Completed
-**Priority:** P0 (Critical) | P1 (High) | P2 (Medium) | P3 (Low)
-**Risk Level:** Low | Medium | High (see docs/private/governance/risk_classification.md)
-**Target Release:** vX.Y.Z
-**Owner:** [Name]
-**Reviewers:** [Names]
-**Created:** YYYY-MM-DD
-**Last Updated:** YYYY-MM-DD
-```
-### 2.1 Overview
-**Brief Description:** One-paragraph summary of what this Feature Unit accomplishes.
-**User Value:** Why this matters to users (connects to product context).
-**Defensible Differentiation:** How this FU validates or enables defensible differentiators (privacy-first, deterministic, cross-platform). If not applicable, explicitly state why.
-**Technical Approach:** High-level approach (which layers, subsystems affected).
-### 2.2 Requirements
-#### Functional Requirements
-1. [Requirement 1]: Detailed description
-2. [Requirement 2]: Detailed description
-#### Non-Functional Requirements
-1. **Performance:** Response time, throughput targets
-2. **Determinism:** How deterministic behavior is ensured
-3. **Consistency:** Consistency tier (strong, bounded eventual, etc.)
-4. **Accessibility:** A11y requirements (keyboard nav, ARIA, etc.)
-5. **Internationalization:** i18n requirements (locales, content language)
-#### Invariants (MUST/MUST NOT)
-**MUST:**
-- [Invariant 1]
-- [Invariant 2]
-**MUST NOT:**
-- [Anti-pattern 1]
-- [Anti-pattern 2]
-### 2.3 Affected Subsystems
-**Primary Subsystems:**
-- [Subsystem 1]: What changes
-- [Subsystem 2]: What changes
-**Dependencies:**
-- Requires [Other Feature Unit ID or dependency]
-- Blocks [Other Feature Unit ID]
-**Documentation to Load:**
-- `docs/subsystems/[relevant_subsystem].md`
-- `docs/architecture/[relevant_architecture].md`
-### 2.4 Schema Changes
-**Tables Affected:**
-- `table_name`: ADD COLUMN `column_name` TYPE
-- `table_name`: CREATE INDEX `index_name` ON ...
-**JSONB Schema Changes:**
-- `records.properties`: Add key `new_field` (schema_version bump to X.Y)
-**Migration Required:** Yes | No
-If yes, include migration file path and description.
-### 2.5 API/MCP Changes
-**New MCP Actions:**
-- `action_name(params)`: Description
-**Modified MCP Actions:**
-- `existing_action(params)`: What changed
-**API Contract:**
-```typescript
-// Request
-interface RequestType {
-  field: type;
-}
-// Response
-interface ResponseType {
-  field: type;
-}
-// Errors
-const POSSIBLE_ERRORS = ["ERROR_CODE_1", "ERROR_CODE_2"];
-```
-### 2.6 UI Changes
-**Components Affected:**
-- `ComponentName`: What changes
-**New Components:**
-- `NewComponent`: Purpose, props, behavior
-**UI States:**
-- Loading state: How displayed
-- Error state: Error message format
-- Empty state: What user sees
-**Accessibility:**
-- Keyboard navigation: Tab order, shortcuts
-- ARIA: Labels, roles, live regions
-- Focus management: Where focus goes
-**Internationalization:**
-- Locale formatting: Dates, numbers
-- Content language: How preserved
-- Translatable strings: List of UI strings
-### 2.7 State Machines
-If introducing new state machine:
-```mermaid
-stateDiagram-v2
-    [*] --> State1
-    State1 --> State2: transition
-    State2 --> [*]
-```
-**States:**
-| State | Terminal | UI Display | Transitions |
-|-------|----------|------------|-------------|
-| State1 | No | "..." | → State2 on event |
-### 2.8 Observability
-**Metrics:**
-- `metric_name_total`: Counter, incremented when...
-- `metric_name_duration_ms`: Histogram, measures...
-**Logs:**
-- Level `info`: "Event description" (fields: field1, field2)
-- Level `error`: "Error description" (fields: error_code, trace_id)
-**Events:**
-- `event.type`: Emitted when... (payload: {...})
-**Traces:**
-- Span name: `operation_name` (attributes: attr1, attr2)
-### 2.9 Testing Strategy
-**Unit Tests:**
-- Test 1: Description
-- Test 2: Description
-**Integration Tests:**
-- Test 1: Description (subsystems involved)
-**E2E Tests:**
-- Test 1: User flow description
-**Property-Based Tests (if applicable):**
-- Property 1: Invariant to verify
-**Test Fixtures:**
-- Fixture 1: Description, location
-**Expected Coverage:**
-- Lines: >80%
-- Branches: >80%
-- Critical paths: 100%
-### 2.10 Error Scenarios
-| Scenario   | Error Code     | Message   | Recovery            |
-| ---------- | -------------- | --------- | ------------------- |
-| Scenario 1 | `ERROR_CODE_1` | "Message" | Retry / User action |
-| Scenario 2 | `ERROR_CODE_2` | "Message" | Manual intervention |
-### 2.11 Rollout and Deployment
-**Feature Flags:** Yes | No
-- If yes: Flag name, default value
-**Rollback Plan:**
-- Rollback steps if feature causes issues
-**Monitoring:**
-- Key metrics to watch post-deployment
-## 3. Complete Example Feature Unit Spec
-````markdown
-# Feature Unit: [FU-2024-01-001] Record Upload with Entity Extraction
-**Status:** In Progress
-**Priority:** P1 (High)
-**Risk Level:** Medium
-**Target Release:** v1.0.0
-**Owner:** Engineering Team
-**Reviewers:** Tech Lead, Product
-**Created:** 2024-01-15
-**Last Updated:** 2024-01-15
-## Overview
-**Brief Description:**
-Implement file upload endpoint that ingests PDFs, extracts text, detects schema type, extracts fields, resolves entities, and inserts into memory graph.
-**User Value:**
-Users can upload invoices, receipts, and contracts, and Neotoma automatically structures them into searchable, AI-ready memory.
-**Technical Approach:**
-- API endpoint: POST /api/upload (Presentation layer)
-- Ingestion service: Orchestrate pipeline (Application layer)
-- Extraction, entity resolution, graph insertion (Domain layer)
-- Store file to S3, insert record to PostgreSQL (Infrastructure layer)
-## Requirements
-### Functional Requirements
-1. **Upload:** Accept PDF files up to 50MB
-2. **Extract:** Extract raw text via pdf-parse or OCR (Tesseract)
-3. **Schema Detection:** Detect FinancialRecord, IdentityDocument, or PDFDocument
-4. **Field Extraction:** Extract invoice_number, amount, vendor_name, etc.
-5. **Entity Resolution:** Generate canonical entity IDs for vendors, people
-6. **Graph Insertion:** Insert record, entities, edges in single transaction
-7. **Response:** Return record with extracted fields
-### Non-Functional Requirements
-1. **Performance:** Complete ingestion in <5s for 10MB PDF
-2. **Determinism:** Same file → same record_id, entities, fields
-3. **Consistency:** Strong consistency (record visible immediately)
-4. **Accessibility:** Upload button keyboard accessible, progress ARIA live region
-5. **Internationalization:** Detect document language, format amounts per locale
-### Invariants
-**MUST:**
-- Extraction MUST be deterministic (rule-based)
-- Entity IDs MUST be hash-based
-- Graph insertion MUST be transactional
-- File hash MUST prevent duplicates
-**MUST NOT:**
-- MUST NOT use LLM extraction (MVP constraint)
-- MUST NOT store PII in logs
-- MUST NOT allow files >50MB
-- MUST NOT proceed if OCR fails (return error)
-## Affected Subsystems
-**Primary Subsystems:**
-- Ingestion: Full pipeline implementation
-- Schema: Uses existing `records` table
-- Entity Resolution: New entity ID generation logic
-**Dependencies:**
-- None (foundational feature)
-**Documentation to Load:**
-- `docs/NEOTOMA_MANIFEST.md`
-- `docs/subsystems/ingestion/ingestion.md`
-- `docs/subsystems/schema.md`
-- `docs/architecture/determinism.md`
-## Schema Changes
-**Tables Affected:**
-- None (uses existing `records` table)
-**JSONB Schema Changes:**
-- `records.properties`: Define FinancialRecord schema v1.0
-**Migration Required:** No
-## API/MCP Changes
-**New MCP Actions:**
-- `upload_file(file: File)`: Upload and ingest file
-**API Contract:**
-```typescript
-// Request (multipart/form-data)
-{
-  file: File; // PDF, max 50MB
-}
-// Response (201 Created)
-{
-  id: string;
-  type: "FinancialRecord" | "IdentityDocument" | "PDFDocument";
-  properties: Record<string, any>;
-  created_at: string;
-}
-// Errors
-[
-  "FILE_TOO_LARGE",
-  "UNSUPPORTED_FILE_TYPE",
-  "EXTRACTION_FAILED",
-  "DB_INSERT_FAILED",
-];
-```
-````
-## UI Changes
-**Components Affected:**
-- `UploadButton`: Add loading state, progress indicator
-- `RecordDetail`: Display extracted fields
-**UI States:**
-- Loading: "Uploading... 45%" (progress bar)
-- Error: "Upload failed: File too large" (error banner)
-- Success: Navigate to /records/{id}
-**Accessibility:**
-- Upload button: `<button>` with aria-label="Upload file"
-- Progress: `<div role="progressbar" aria-valuenow={45} aria-valuemax={100}>`
-- Error: `<div role="alert">Error message</div>`
-## Observability
-**Metrics:**
-- `record_upload_total`: Counter (labels: status=success|failed)
-- `record_upload_duration_ms`: Histogram
-- `extraction_errors_total`: Counter (labels: error_code)
-**Logs:**
-- `info`: "File uploaded" (fields: record_id, type, file_size_bytes)
-- `error`: "Extraction failed" (fields: error_code, trace_id)
-**Events:**
-- `record.created`: Emitted after successful insert
-## Testing Strategy
-**Unit Tests:**
-- `extractFieldsForFinancialRecord()`: Verify regex extraction
-- `generateEntityId()`: Verify deterministic IDs
-- `detectSchemaType()`: Verify schema detection rules
-**Integration Tests:**
-- Upload → extract → insert: Verify record in DB with entities
-**E2E Tests:**
-- User uploads invoice → sees record detail with extracted fields
-**Expected Coverage:**
-- Lines: 85%
-- Branches: 85%
-- Critical paths (ingestion, extraction): 100%
-## Error Scenarios
-| Scenario         | Error Code              | Message                        | Recovery            |
-| ---------------- | ----------------------- | ------------------------------ | ------------------- |
-| File > 50MB      | `FILE_TOO_LARGE`        | "File exceeds 50MB limit"      | Upload smaller file |
-| Unsupported type | `UNSUPPORTED_FILE_TYPE` | "Only PDF, JPG, PNG supported" | Convert file        |
-| OCR failure      | `OCR_FAILED`            | "Could not extract text"       | Retry               |
-## Rollout and Deployment
-**Feature Flags:** No
-**Rollback Plan:**
-- Revert API endpoint deployment
-- No DB changes to rollback
-**Monitoring:**
-- Watch `record_upload_total` for success rate >95%
-- Watch `record_upload_duration_ms` P95 <5s
-```
-## Agent Instructions
-### When to Load This Document
-Load when planning a new Feature Unit, reviewing a Feature Unit spec, or understanding the Feature Unit concept.
-### Required Co-Loaded Documents
-- `docs/NEOTOMA_MANIFEST.md` (invariants and product context)
-- `docs/feature_units/standards/manifest_template.yaml` (manifest structure)
-- `docs/feature_units/standards/execution_instructions.md` (implementation flow)
-### Constraints Agents Must Enforce
-1. All Feature Units MUST follow this template
-2. All Feature Units MUST include manifest
-3. All Feature Units MUST specify tests
-4. All Feature Units MUST document observability
-5. All Feature Units MUST respect Truth Layer boundaries
-6. All Feature Units MUST be deterministic where applicable
-### Forbidden Patterns
-- Starting implementation without spec
-- Incomplete spec (missing required sections)
-- Feature Unit that violates invariants
-- Feature Unit without tests
-- Feature Unit without observability plan
-### Validation Checklist
-- [ ] All template sections completed
-- [ ] Invariants documented (MUST/MUST NOT)
-- [ ] Testing strategy defined
-- [ ] Observability metrics/logs/events specified
-- [ ] Schema changes documented with migrations
-- [ ] API contracts fully specified
-- [ ] UI accessibility requirements documented
-- [ ] Error scenarios enumerated
-- [ ] Rollout plan defined
-- [ ] Foundational docs loaded and followed
-```

package/docs/feature_units/standards/integration_test_execution.md

@@ -1,127 +0,0 @@
-# Integration Test Execution Guide
-**Purpose:** Defines when and how integration tests are executed during release builds.
-**Related Documents:**
-- [`release_workflow.md`](./release_workflow.md) — Release workflow integration
-- [`release_orchestrator.js`](../../../scripts/release_orchestrator.js) — Orchestrator implementation
-## Overview
-Integration tests are **ALWAYS executed automatically** during the release build process (REQUIRED):
-1. **After each batch completes:** Batch-level integration tests run
-2. **After all batches complete:** Full integration test suite runs automatically (CANNOT BE SKIPPED)
-**Critical:** The release orchestrator **MUST** run the full integration test suite after all batches complete. This is a required step in the release build process.
-Test results are automatically updated in `status.md` and reflected in release reports.
-## Execution Flow
-### 1. Batch-Level Integration Tests
-**When:** After each batch completes (all FUs in batch are `completed`)
-**What runs:**
-- Tests from `integration_tests.md` that cover the completed batch
-- Determined by "Batches Covered" field in test definition
-**How:**
-- Orchestrator calls `runIntegrationTests(batchId, releaseId)`
-- Parses `integration_tests.md` to find tests for the batch
-- Executes test commands (if test files exist)
-- Updates batch status based on test results
-**Failure handling:**
-- If batch-level tests fail → batch marked as failed, release execution stops
-- User must fix issues and re-run
-### 2. Full Integration Test Suite
-**When:** After ALL batches complete
-**What runs:**
-- ALL tests from `integration_tests.md` (IT-001 through IT-XXX)
-- Complete end-to-end validation of all Feature Units
-**How:**
-- **Orchestrator AUTOMATICALLY calls `runFullIntegrationTestSuite(releaseId)`** after all batches complete
-- This is a **REQUIRED** step in the release build process
-- Parses all tests from `integration_tests.md`
-- Executes each test command (if defined)
-- Updates `status.md` integration test status table with results
-**Test Status Values:**
-- `passed`: Test executed and passed
-- `failed`: Test executed and failed
-- `not_run`: Test command not defined or test file missing (acceptable for initial releases)
-**Failure handling:**
-- If any test **fails** → release status remains `in_progress`
-- Release cannot be marked `ready_for_deployment` until all tests pass
-- If tests show `not_run` → release can proceed, but tests should be implemented for full validation
-- User must fix issues and re-run tests
-## Test Status Values
-Integration tests can have three status values:
-- **`passed`** ✅ — Test executed and passed
-- **`failed`** ❌ — Test executed and failed
-- **`not_run`** ⏳ — Test not executed (no command defined or test file missing)
-## Test Command Resolution
-Tests are executed if:
-1. **Test command is defined** in `integration_tests.md`:
-   - Look for `test: "path/to/test/file.ts"` field
-   - Or extract from "Machine-Checkable" section
-2. **Test file exists** at the specified path
-3. **Test executes successfully** via npm:
-   ```bash
-   npm run test:integration -- path/to/test/file.ts
-   ```
-If test command is missing or test file doesn't exist:
-- Test is marked as `not_run` (⏳)
-- Does not fail the release
-- Shows up in report as not executed
-## Status.md Updates
-The orchestrator automatically updates `status.md`:
-**After full test suite:**
-- Updates integration test status table (Section 5)
-- Sets status to `passed`, `failed`, or `not_run` for each test
-- Updates summary: "X/Y tests passed"
-**Format:**
-```markdown
-| Test ID | Name                                  | Status     |
-| ------- | ------------------------------------- | ---------- |
-| IT-001  | File Upload → Extraction → Query Flow | ✅ passed  |
-| IT-002  | Entity Resolution Validation          | ❌ failed  |
-| IT-003  | Timeline Event Validation             | ⏳ not_run |
-```
-## Manual Execution
-If orchestrator is not used (manual release execution):
-1. **Run tests manually:**
-   ```bash
-   npm run test:integration -- tests/integration/mcp_workflow.test.ts
-   npm run test:integration -- tests/integration/entity_resolution.test.ts
-   # ... etc for all tests
-   ```
-2. **Update status.md manually:**
-   - Update integration test status table
-   - Set status to `passed` or `failed` for each test
-   - Update summary count
-3. **Verify all tests pass** before marking release as `ready_for_deployment`
-## Why Tests Might Not Run
-Tests may show as `not_run` if:
-1. **Test command not defined** in `integration_tests.md`
-   - Solution: Add `test: "path/to/test/file.ts"` to test definition
-2. **Test file doesn't exist yet**
-   - Solution: Create test file at specified path
-3. **Orchestrator not executed**
-   - Solution: Run orchestrator or execute tests manually
-4. **Test execution skipped** (test file missing during batch execution)
-   - Solution: Ensure test files exist before running orchestrator
-## Integration with Release Reports
-Release reports automatically reflect integration test status:
-- **Section 4.1:** Test execution summary table (shows all tests with status)
-- **Section 4.2:** Detailed test case descriptions (from `integration_tests.md`)
-- **Metrics:** Integration test pass rate calculated from status
-Reports are generated from `status.md`, so test results must be updated there for reports to reflect them.
-## Best Practices
-1. **Define test commands** in `integration_tests.md` for all tests
-2. **Create test files** before running orchestrator
-3. **Run full test suite** after all batches complete (automatic via orchestrator)
-4. **Update status.md** if running tests manually
-5. **Verify all tests pass** before marking release as `ready_for_deployment`
-## Troubleshooting
-**Tests not running:**
-- Check if orchestrator is being used
-- Verify test commands are defined in `integration_tests.md`
-- Verify test files exist at specified paths
-- Check orchestrator logs for errors
-**Tests showing as not_run:**
-- Add test commands to `integration_tests.md`
-- Create missing test files
-- Re-run orchestrator after adding tests
-**Tests failing:**
-- Fix failing tests
-- Re-run orchestrator or tests manually
-- Update `status.md` when tests pass