neotoma 0.3.0 → 0.3.2

package/docs/developer/observation_architecture_documentation_integration.md

@@ -1,368 +0,0 @@
-name: Observation Architecture Documentation Integration
-overview: "Documentation-only plan: Integrate 4-layer observation architecture (Document→Entity→Observation→Snapshot) into Neotoma documentation system and v0.1.0 release documentation. Updates existing docs to reflect architectural decisions, adds new architectural decisions document, and updates release manifests. NO CODE IMPLEMENTATION—documentation only."
-todos:
-  - id: create-arch-decisions-doc
-    content: Create docs/architecture/architectural_decisions.md with 11 decisions
-    status: completed
-  - id: update-manifest
-    content: Update NEOTOMA_MANIFEST.md for 4-layer model and observation concepts
-    status: completed
-    dependencies:
-      - create-arch-decisions-doc
-  - id: update-architecture-md
-    content: Update architecture.md to include observation layer in domain services
-    status: completed
-    dependencies:
-      - create-arch-decisions-doc
-  - id: update-schema-md
-    content: Update schema.md with new tables (observations, snapshots, registry, fragments)
-    status: completed
-    dependencies:
-      - create-arch-decisions-doc
-  - id: update-record-types
-    content: Update record_types.md for observation emission patterns
-    status: completed
-    dependencies:
-      - update-schema-md
-  - id: update-ingestion-md
-    content: Update ingestion.md with observation creation step
-    status: completed
-    dependencies:
-      - update-schema-md
-  - id: create-reducer-doc
-    content: Create reducer.md subsystem documentation
-    status: completed
-    dependencies:
-      - create-arch-decisions-doc
-  - id: create-relationships-doc
-    content: Create relationships.md subsystem documentation
-    status: completed
-    dependencies:
-      - create-arch-decisions-doc
-  - id: create-observation-arch-doc
-    content: Create observation_architecture.md overview
-    status: completed
-    dependencies:
-      - create-arch-decisions-doc
-  - id: update-determinism
-    content: Update determinism.md with reducer requirements
-    status: completed
-    dependencies:
-      - create-reducer-doc
-  - id: update-consistency
-    content: Update consistency.md for observation/snapshot consistency
-    status: completed
-    dependencies:
-      - create-observation-arch-doc
-  - id: update-data-models
-    content: Rewrite DATA_MODELS.md for 4-layer architecture
-    status: completed
-    dependencies:
-      - update-schema-md
-  - id: update-mcp-spec
-    content: Update MCP_SPEC.md with new actions that SHOULD be implemented
-    status: completed
-    dependencies:
-      - create-observation-arch-doc
-  - id: update-feature-units
-    content: Update MVP_FEATURE_UNITS.md with FU-055 through FU-061
-    status: completed
-    dependencies:
-      - create-observation-arch-doc
-  - id: update-v0.1.0-manifest
-    content: Update v0.1.0/manifest.yaml with new Feature Units
-    status: completed
-    dependencies:
-      - update-feature-units
-  - id: update-v0.1.0-release-plan
-    content: Update v0.1.0/release_plan.md with observation architecture scope
-    status: completed
-    dependencies:
-      - update-v0.1.0-manifest
-  - id: update-v0.1.0-integration-tests
-    content: Update v0.1.0/integration_tests.md with observation test scenarios
-    status: completed
-    dependencies:
-      - update-v0.1.0-release-plan
-  - id: update-context-index
-    content: Update context/index.md with new docs and reading strategies
-    status: completed
-    dependencies:
-      - create-arch-decisions-doc
-      - create-reducer-doc
-      - create-relationships-doc
-  - id: validate-cross-refs
-    content: Validate all cross-references and terminology consistency
-    status: completed
-    dependencies:
-      - update-context-index
-      - update-v0.1.0-integration-tests
-# Observation Architecture Documentation Integration — v0.1.0 Release
-## Executive Summary
-**Scope: Documentation Updates Only**
-This plan integrates the 11 architectural decisions document into Neotoma's documentation system and v0.1.0 release documentation. This is a **documentation task only**—no code implementation.
-**What This Plan Does:**
-- Creates new architectural decisions document
-- Updates existing documentation to reflect 4-layer truth model
-- Updates v0.1.0 release documentation to include observation architecture
-- Documents what SHOULD be implemented (not implementing it)
-**What This Plan Does NOT Do:**
-- ❌ Implement database tables or code
-- ❌ Write reducer logic or services
-- ❌ Modify ingestion pipeline code
-- ❌ Create MCP actions
-- ❌ Write tests or run code
-## Phase 1: Create Core Architectural Decisions Document
-### Task 1.1: Create Architectural Decisions Doc
-**Create:** [`docs/architecture/architectural_decisions.md`](docs/architecture/architectural_decisions.md)
-**Content:**
-- Format the 11 architectural decisions provided by user
-- Add proper markdown structure per documentation standards
-- Add Mermaid diagrams for 4-layer truth model
-- Add cross-references to related docs
-- Add "Agent Instructions" section
-- Add validation checklist
-**Deliverable:** Complete architectural decisions document
-## Phase 2: Update Foundation Documentation
-### Task 2.1: Update NEOTOMA_MANIFEST.md
-**File:** [`docs/NEOTOMA_MANIFEST.md`](docs/NEOTOMA_MANIFEST.md)
-**Updates:**
-- Section 2.1 Core Responsibilities: Add observation creation, reducer execution, schema registry management
-- Section 6 Data Model: Replace 3-layer with 4-layer model (Document → Entity → Observation → Snapshot)
-- Add reducer concepts to determinism section
-- Update vocabulary to include observation, snapshot, reducer terms
-**Deliverable:** Updated manifest reflecting 4-layer architecture
-### Task 2.2: Update architecture.md
-**File:** [`docs/architecture/architecture.md`](docs/architecture/architecture.md)
-**Updates:**
-- Section 2 Internal Architecture: Add Observation Storage, Reducer Engine, Schema Registry as domain services
-- Section 4.1 Ingestion Flow: Insert observation creation + reducer execution steps between extraction and graph insertion
-- Update all data flow diagrams to show observation layer
-- Section 9 Architectural Invariants: Add reducer determinism, observation provenance requirements
-- Add references to architectural_decisions.md
-**Deliverable:** Updated architecture doc with observation layer
-## Phase 3: Update Subsystem Documentation
-### Task 3.1: Update schema.md
-**File:** [`docs/subsystems/schema.md`](docs/subsystems/schema.md)
-**Updates:**
-- Add `schema_registry` table documentation
-- Add `observations` table documentation
-- Add `entity_snapshots` table documentation
-- Add `raw_fragments` table documentation
-- Document observation schemas vs entity schemas
-- Add reducer configuration schema documentation
-- Document schema versioning for observations
-**Deliverable:** Updated schema documentation
-### Task 3.2: Update record_types.md
-**File:** [`docs/subsystems/record_types.md`](docs/subsystems/record_types.md)
-**Updates:**
-- Reframe as "observation emission patterns" rather than direct field extraction
-- Add reducer merge policy per record type
-- Document specificity_score calculation rules
-- Add source_priority rules per type
-- Update examples to show observation → snapshot flow
-**Deliverable:** Updated record types documentation
-### Task 3.3: Update ingestion.md
-**File:** [`docs/subsystems/ingestion/ingestion.md`](docs/subsystems/ingestion/ingestion.md)
-**Updates:**
-- Add observation layer to pipeline description
-- Document observation creation step
-- Document reducer invocation after observation creation
-- Update pipeline diagram to show 4-layer flow
-- Add raw_fragments handling step
-**Deliverable:** Updated ingestion documentation
-### Task 3.4: Create reducer.md
-**File:** [`docs/subsystems/reducer.md`](docs/subsystems/reducer.md) (NEW)
-**Content:**
-- Document reducer engine architecture
-- Explain merge strategies (last_write, highest_priority, most_specific, merge_array)
-- Provide examples of reducer execution
-- Document determinism requirements
-- Add testing patterns
-- Cross-reference architectural_decisions.md
-**Deliverable:** New reducer subsystem documentation
-### Task 3.5: Create relationships.md
-**File:** [`docs/subsystems/relationships.md`](docs/subsystems/relationships.md) (NEW)
-**Content:**
-- Document relationship types (PART_OF, CORRECTS, REFERS_TO, SETTLES, DUPLICATE_OF)
-- Explain graph patterns
-- Provide examples
-- Add query patterns
-- Document relationship metadata
-**Deliverable:** New relationships subsystem documentation
-### Task 3.6: Create observation_architecture.md
-**File:** [`docs/subsystems/observation_architecture.md`](docs/subsystems/observation_architecture.md) (NEW)
-**Content:**
-- Complete overview of observation architecture
-- 4-layer model explanation
-- Observation lifecycle
-- Snapshot computation flow
-- Provenance tracking
-- Integration with existing event-sourcing (FU-050)
-**Deliverable:** New observation architecture overview
-## Phase 4: Update Cross-Cutting Documentation
-### Task 4.1: Update determinism.md
-**File:** [`docs/architecture/determinism.md`](docs/architecture/determinism.md)
-**Updates:**
-- Add reducer determinism requirements (same observations + merge rules → same snapshot)
-- Add observation ordering guarantees
-- Add ID generation rules for observations
-- Add examples of deterministic reducer execution
-**Deliverable:** Updated determinism documentation
-### Task 4.2: Update consistency.md
-**File:** [`docs/architecture/consistency.md`](docs/architecture/consistency.md)
-**Updates:**
-- Add consistency tier for observations (strong consistency)
-- Add snapshot recomputation consistency (when do snapshots refresh?)
-- Document eventual consistency for snapshot indexes if applicable
-- Update consistency mapping table
-**Deliverable:** Updated consistency documentation
-## Phase 5: Update Specs Documentation
-### Task 5.1: Update DATA_MODELS.md
-**File:** [`docs/specs/DATA_MODELS.md`](docs/specs/DATA_MODELS.md)
-**Updates:**
-- Complete rewrite of data model section for 4-layer architecture
-- Add observation model documentation
-- Add snapshot model documentation
-- Add reducer configuration model
-- Update all diagrams to show observation layer
-**Deliverable:** Updated data models specification
-### Task 5.2: Update MCP_SPEC.md
-**File:** [`docs/specs/MCP_SPEC.md`](docs/specs/MCP_SPEC.md)
-**Updates:**
-- Document new MCP actions that SHOULD be implemented:
-- `get_entity_snapshot` — Get entity with provenance
-- `list_observations` — Query observations for entity
-- `get_field_provenance` — Trace field to source documents
-- `create_relationship` — Create typed relationship
-- `list_relationships` — Query entity relationships
-- Update existing action documentation to reference snapshots
-- Add provenance query examples
-**Deliverable:** Updated MCP specification
-### Task 5.3: Update MVP_FEATURE_UNITS.md
-**File:** [`docs/specs/MVP_FEATURE_UNITS.md`](docs/specs/MVP_FEATURE_UNITS.md)
-**Updates:**
-- Add new Feature Units that SHOULD be created:
-- FU-055: Observation Storage Layer
-- FU-056: Enhanced Reducer Engine for Observations
-- FU-057: Schema Registry Service
-- FU-058: Observation-Aware Ingestion Pipeline
-- FU-059: Relationship Types
-- FU-060: Automated Schema Promotion (optional P1)
-- FU-061: MCP Actions for Observation Architecture
-- Document dependencies between new FUs and existing FUs
-- Add to execution schedule
-**Deliverable:** Updated feature units specification
-## Phase 6: Update Release Documentation
-### Task 6.1: Update v0.1.0 manifest.yaml
-**File:** [`docs/releases/in_progress/v0.1.0/manifest.yaml`](docs/releases/in_progress/v0.1.0/manifest.yaml)
-**Updates:**
-- Add new Feature Units (FU-055 through FU-061) to feature_units list
-- Document dependencies
-- Add to execution_schedule batches
-- Update acceptance_criteria to include observation architecture criteria
-**Deliverable:** Updated v0.1.0 manifest
-### Task 6.2: Update v0.1.0 release_plan.md
-**File:** [`docs/releases/in_progress/v0.1.0/release_plan.md`](docs/releases/in_progress/v0.1.0/release_plan.md)
-**Updates:**
-- Section 2.1: Add observation architecture Feature Units
-- Section 3: Add observation architecture acceptance criteria
-- Section 4: Add observation architecture integration scenarios
-- Section 7: Add observation architecture success criteria
-- Document relationship to existing event-sourcing foundation (FU-050)
-**Deliverable:** Updated v0.1.0 release plan
-### Task 6.3: Update v0.1.0 integration_tests.md
-**File:** [`docs/releases/in_progress/v0.1.0/integration_tests.md`](docs/releases/in_progress/v0.1.0/integration_tests.md)
-**Updates:**
-- Add integration test scenarios for observation architecture:
-- Multi-source entity resolution test
-- Observation reducer validation test
-- Relationship graph validation test
-- Schema registry validation test
-- Document test specifications (not implementing tests, just documenting what SHOULD be tested)
-**Deliverable:** Updated integration test specifications
-## Phase 7: Update Context and Navigation
-### Task 7.1: Update context/index.md
-**File:** Foundation rules in `.cursor/rules/`
-**Updates:**
-- Section 2.2 Architecture: Add architectural_decisions.md to architecture table
-- Section 3 Dependency Graph: Add architectural_decisions.md node (depends on NEOTOMA_MANIFEST, architecture.md)
-- Section 4 Reading Strategies: Add reading strategies for:
-- Reducer implementation work
-- Observation debugging
-- Schema registry work
-- Relationship graph queries
-- Add new subsystem docs to appropriate sections
-**Deliverable:** Updated context index
-## Phase 8: Validate Documentation Consistency
-### Task 8.1: Cross-Reference Validation
-**Tasks:**
-- Search all docs for references to "extracted_fields", "entity resolution", "record creation"
-- Verify consistency with 4-layer model terminology
-- Update all mermaid diagrams showing data flow to include observation layer
-- Verify all "Agent Instructions" sections reference architectural_decisions.md when relevant
-- Check that no docs contradict the new canonical model
-**Deliverable:** Documentation consistency report
-### Task 8.2: Terminology Consistency
-**Tasks:**
-- Update vocabulary.md if it exists, or create vocabulary section
-- Ensure consistent use of:
-- "observation" vs "extracted field"
-- "snapshot" vs "entity state"
-- "reducer" vs "merge logic"
-- "schema registry" vs "schema definitions"
-**Deliverable:** Consistent terminology across all docs
-## Documentation Standards Compliance
-### All Documents Must Follow:
-- [`docs/conventions/documentation_standards.md`](docs/conventions/documentation_standards.md) formatting rules
-- Proper Mermaid diagram syntax
-- MUST/MUST NOT language conventions
-- Agent Instructions sections where appropriate
-- Cross-references to related documents
-## Deliverables Summary
-**New Documents Created:**
-1. `docs/architecture/architectural_decisions.md` — 11 architectural decisions
-2. `docs/subsystems/reducer.md` — Reducer engine documentation
-3. `docs/subsystems/relationships.md` — Relationship types guide
-4. `docs/subsystems/observation_architecture.md` — Observation architecture overview
-**Documents Updated:**
-1. `docs/NEOTOMA_MANIFEST.md` — 4-layer model, observation concepts
-2. `docs/architecture/architecture.md` — Observation layer in domain services
-3. `docs/subsystems/schema.md` — New tables (observations, snapshots, registry, fragments)
-4. `docs/subsystems/record_types.md` — Observation emission patterns
-5. `docs/subsystems/ingestion/ingestion.md` — Observation creation step
-6. `docs/architecture/determinism.md` — Reducer determinism
-7. `docs/architecture/consistency.md` — Observation/snapshot consistency
-8. `docs/specs/DATA_MODELS.md` — 4-layer model rewrite
-9. `docs/specs/MCP_SPEC.md` — New MCP actions
-10. `docs/specs/MVP_FEATURE_UNITS.md` — New Feature Units (FU-055 through FU-061)
-11. Foundation rules in `.cursor/rules/` — Agent instructions and documentation loading order
-12. `docs/releases/in_progress/v0.1.0/manifest.yaml` — New Feature Units
-13. `docs/releases/in_progress/v0.1.0/release_plan.md` — Observation architecture scope
-14. `docs/releases/in_progress/v0.1.0/integration_tests.md` — Test scenarios
-## Validation Checklist
-- [ ] All 11 architectural decisions documented in architectural_decisions.md
-- [ ] 4-layer model (Document → Entity → Observation → Snapshot) documented throughout
-- [ ] Reducer concept integrated across relevant subsystems
-- [ ] Schema registry documented in schema.md
-- [ ] Observation provenance patterns documented
-- [ ] All data flow diagrams show observation layer
-- [ ] MCP actions documented (what SHOULD be implemented)
-- [ ] Feature Units documented (FU-055 through FU-061)
-- [ ] No contradictions between architectural_decisions.md and other docs
-- [ ] context/index.md reading strategies updated
-- [ ] All cross-references validated
-- [ ] v0.1.0 release docs updated
-- [ ] Terminology consistent across all docs
-- [ ] Documentation standards compliance verified
-## Important Notes
-**This is a documentation task only:**
-- We are documenting WHAT SHOULD be implemented
-- We are NOT implementing code, database tables, or services
-- We are updating documentation to reflect architectural decisions
-- Future implementation work will reference these updated docs
-**Relationship to v0.1.0:**
-- v0.1.0 already includes event-sourcing foundation (FU-050 through FU-054)
-- Observation architecture builds on that foundation
-- Documentation reflects how observation architecture SHOULD integrate with existing foundation
-- Release documentation updated to show observation architecture as part of v0.1.0 scope

package/docs/developer/release_orchestrator.md

@@ -1,197 +0,0 @@
-# Release Orchestrator
-## Overview
-The Release Orchestrator supports two execution modes:
-1. **Single-Agent Mode**: Executes Feature Units sequentially with model recommendations based on release complexity
-2. **Multi-Agent Mode**: Spawns and coordinates worker agents for parallel Feature Unit execution using Cursor's Cloud Agents API, reducing calendar time by 25-35% compared to sequential execution
-## Prerequisites
-### For All Modes
-- **Pre-Release Validation**: Run `docs/developer/pre_release_checklist.md` before marking release as `ready_for_deployment`
-
-### For Single-Agent Mode
-- No special prerequisites required
-- Model recommendation provided based on release analysis
-### For Multi-Agent Mode
-1. **Cursor Cloud Subscription**: Requires Background Agents enabled
-2. **API Credentials**: Configure environment variables:
-   ```bash
-   export CURSOR_CLOUD_API_URL="https://api.cursor.com/v1"
-   export CURSOR_CLOUD_API_KEY="your_api_key_here"
-   export REPO_URL="https://github.com/your-org/neotoma"
-   export RELEASE_BRANCH="main"  # Optional, defaults to 'main'
-   ```
-3. **Release Manifest**: Set `execution_strategy.type: "multi_agent"` in `manifest.yaml` (or select via prompt)
-## Usage
-### Start Orchestrator
-```bash
-node scripts/release_orchestrator.js <release_id>
-```
-**Example:**
-```bash
-node scripts/release_orchestrator.js v0.1.0
-```
-### Execution Strategy Selection
-When you start the orchestrator, it will:
-1. Check `manifest.yaml` for `execution_strategy.type`
-2. If not set, **prompt you** to select execution mode:
-   ```
-   === Release Execution Strategy Selection ===
-   
-   How would you like to execute this release build?
-     1. Single-agent (sequential execution)
-     2. Multi-agent (parallel execution)
-   
-   Enter choice (1 or 2):
-   ```
-3. If single-agent is selected, display model recommendation:
-   ```
-   [INFO] Model recommendation: claude-3-5-sonnet-20241022 (medium tier)
-   [INFO] Reasoning: Release has 8 FUs with average complexity 4.2, 2 high-risk FUs, 
-         5 P0 FUs, 4 batches, and estimated 22.5 hours total. Medium tier model 
-         recommended for balanced performance and cost.
-   [INFO] Note: Use this model in your Cursor session for optimal execution
-   ```
-4. Save selected strategy to `manifest.yaml` for future runs
-### Monitor Execution
-The orchestrator creates a status file at:
-```
-docs/releases/in_progress/<release_id>/agent_status.json
-```
-Monitor progress:
-```bash
-# Watch status file
-watch -n 5 cat docs/releases/in_progress/v0.1.0/agent_status.json
-# Or use jq for formatted output
-watch -n 5 'cat docs/releases/in_progress/v0.1.0/agent_status.json | jq .'
-```
-## How It Works
-### 1. Orchestrator Startup
-- Loads `manifest.yaml` and `execution_schedule.md`
-- Initializes `agent_status.json`
-- Prompts for execution strategy if not set in `manifest.yaml`
-- For single-agent mode: Analyzes release and recommends model
-- For multi-agent mode: Validates prerequisites (API credentials)
-### 2. Batch Execution
-For each batch in execution schedule:
-1. **Check Dependencies**: Verify previous batches complete
-2. **Check Limits**: Ensure `max_parallel_fus` not exceeded
-3. **Spawn Workers**: Create background agents for each FU in batch
-4. **Monitor Progress**: Poll status file every minute
-5. **Run Tests**: Execute integration tests after batch completion
-6. **Mark Complete**: Update batch status to `completed`
-### 3. Worker Agents
-Each worker agent:
-- Loads FU specification
-- Executes Feature Unit workflow
-- Updates status file every 5-10 minutes
-- Reports completion or failures
-## Status File Structure
-```json
-{
-  "release_id": "v0.1.0",
-  "orchestrator": {
-    "agent_id": "orch_1234567890",
-    "started_at": "2024-01-15T10:00:00Z",
-    "current_batch": 0,
-    "status": "running"
-  },
-  "batches": [
-    {
-      "batch_id": 0,
-      "status": "running",
-      "started_at": "2024-01-15T10:00:00Z",
-      "feature_units": [
-        {
-          "fu_id": "FU-100",
-          "worker_agent_id": "worker_1234567890_abc",
-          "status": "running",
-          "progress": 0.3,
-          "started_at": "2024-01-15T10:00:05Z",
-          "last_update": "2024-01-15T10:15:00Z"
-        }
-      ]
-    }
-  ],
-  "errors": [],
-  "completed_fus": []
-}
-```
-## Configuration
-### Manifest Configuration
-Add to `docs/releases/in_progress/<release_id>/manifest.yaml`:
-```yaml
-execution_strategy:
-  type: "single_agent" # or "multi_agent" (defaults to prompt if not set)
-  max_parallel_fus: 3  # For multi-agent mode only
-  max_high_risk_in_parallel: 1  # For multi-agent mode only
-  agent_spawning:  # For multi-agent mode only
-    enabled: true
-    status_tracking: "file" # or "api"
-    status_file: "docs/releases/in_progress/v0.1.0/agent_status.json"
-```
-**Note:** If `execution_strategy.type` is not set, the orchestrator will prompt you to choose when starting the release build.
-### Environment Variables
-**For Multi-Agent Mode Only:**
-| Variable               | Description               | Required             |
-| ---------------------- | ------------------------- | -------------------- |
-| `CURSOR_CLOUD_API_URL` | Cursor Cloud API endpoint | Yes (multi-agent)    |
-| `CURSOR_CLOUD_API_KEY` | API authentication key    | Yes (multi-agent)    |
-| `REPO_URL`             | Repository URL            | Yes (multi-agent)    |
-| `RELEASE_BRANCH`       | Branch to execute on      | No (default: `dev`)  |
-**For Single-Agent Mode:**
-No special environment variables required. The orchestrator will recommend a model based on release complexity analysis.
-## Failure Handling
-### Worker Agent Failures
-- **Timeout**: Agent exceeds `max_duration_minutes` → Mark as failed
-- **Stale Status**: No update for 15+ minutes → Mark as stale
-- **Error Reported**: Worker sets `status: "failed"` → Handle failure
-### Recovery Strategies
-1. **Automatic Retry**: P0 FUs retry up to 3 times
-2. **Single Retry**: P1 FUs retry once
-3. **Escalation**: P2 FUs or repeated failures → Human intervention
-### Batch Failures
-If integration tests fail:
-1. Stop all active workers in batch
-2. Report failure to orchestrator
-3. Present options to user:
-   - Fix and retry batch
-   - Skip batch (defer FUs)
-   - Abort release
-## Troubleshooting
-### Orchestrator Not Starting
-**Check:**
-- Execution schedule file exists
-- For multi-agent mode: `execution_strategy.type` is `"multi_agent"` in manifest (or select via prompt)
-- For multi-agent mode: API credentials are set (CURSOR_CLOUD_API_URL, CURSOR_CLOUD_API_KEY, REPO_URL)
-### Workers Not Spawning
-**Check:**
-- API credentials are valid
-- Cursor Cloud subscription has Background Agents enabled
-- Execution limits not exceeded
-### Status File Not Updating
-**Check:**
-- File permissions (workers need write access)
-- File locking (concurrent updates)
-- Worker agents are running
-### Batch Stuck
-**Check:**
-- Worker agents are still active (poll API)
-- Dependencies are complete
-- No errors in status file
-## Implementation Status
-### ✅ Completed
-- Orchestrator script structure
-- Status file management
-- Batch dependency checking
-- Execution limit enforcement
-- Worker agent instructions template
-### ⏳ TODO (Phase 1)
-- [ ] Integrate actual Cursor Cloud Agents API calls
-- [ ] Implement file locking for status updates
-- [ ] Add retry logic for failed FUs
-- [ ] Add integration test execution
-- [ ] Add monitoring dashboard
-### ⏳ TODO (Phase 2)
-- [ ] API-based status tracking (instead of file)
-- [ ] Dynamic load balancing
-- [ ] Resource monitoring
-- [ ] Cost optimization

package/docs/developer/repository_cleanup_plan.md

@@ -1,87 +0,0 @@
-name: Repository Cleanup and Reorganization
-overview: Clean up outdated files, remove build artifacts, reorganize documentation, and improve repository structure
-todos:
-  - id: remove-outdated-docs
-    content: Delete CLAUDE.md and SETUP_INSTRUCTIONS.md from root directory
-    status: completed
-  - id: remove-build-artifacts
-    content: Remove public/assets/ build artifacts from git tracking and add to .gitignore
-    status: completed
-  - id: remove-system-files
-    content: Remove .DS_Store and neotoma.code-workspace from git tracking
-    status: completed
-  - id: move-script-docs
-    content: Move scripts/README_RELEASE_ORCHESTRATOR.md to docs/developer/release_orchestrator.md
-    status: completed
-  - id: move-worker-template
-    content: Move scripts/worker_agent_template.md to docs/feature_units/standards/worker_agent_template.md
-    status: completed
-  - id: update-references
-    content: Update any references to moved files in documentation and scripts
-    status: completed
-  - id: verify-gitignore
-    content: Verify .gitignore properly excludes all build artifacts and system files
-    status: completed
-# Repository Cleanup and Reorganization Plan
-## Issues Identified
-### 1. Outdated Documentation Files
-- **CLAUDE.md** (root): Outdated documentation referencing old "objects" table architecture instead of current "records" table. Mentions deprecated architecture.
-- **SETUP_INSTRUCTIONS.md** (root): Duplicates content from `docs/developer/getting_started.md` and contains outdated references to "objects" table.
-### 2. Build Artifacts Committed
-- **public/assets/main-*.js** and **public/assets/main-*.css**: Build artifacts from Vite that should not be committed to git. These are generated files.
-### 3. System Files Committed
-- **.DS_Store** files: macOS system files committed in root and docs/ directories. Already in .gitignore but files exist.
-- **neotoma.code-workspace**: VS Code workspace file committed. Already in .gitignore but file exists.
-### 4. Script Documentation Organization
-- **scripts/README_RELEASE_ORCHESTRATOR.md**: Documentation file in scripts directory. Should be moved to `docs/developer/` or `docs/feature_units/standards/`.
-- **scripts/worker_agent_template.md**: Template file in scripts directory. Should be moved to `docs/feature_units/standards/` or `docs/developer/`.
-## Proposed Changes
-### Phase 1: Remove Outdated Documentation
-1. **Delete CLAUDE.md** - Outdated and references wrong architecture
-2. **Delete SETUP_INSTRUCTIONS.md** - Superseded by `docs/developer/getting_started.md`
-### Phase 2: Remove Build Artifacts
-1. **Remove public/assets/** directory from git tracking
-- Add `public/assets/` to `.gitignore` if not already present
-- Remove committed build artifacts: `public/assets/main-*.js` and `public/assets/main-*.css`
-### Phase 3: Clean System Files
-1. **Remove .DS_Store files** from git tracking
-- Already in `.gitignore`, but remove existing committed files
-2. **Remove neotoma.code-workspace** from git tracking
-- Already in `.gitignore`, but remove existing committed file
-### Phase 4: Reorganize Script Documentation
-1. **Move scripts/README_RELEASE_ORCHESTRATOR.md** → `docs/developer/release_orchestrator.md`
-2. **Move scripts/worker_agent_template.md** → `docs/feature_units/standards/worker_agent_template.md`
-3. Update any references to these files in:
-- `docs/feature_units/standards/multi_agent_orchestration.md`
-- `scripts/release_orchestrator.js` (if it references the README)
-- Any other documentation that references these files
-### Phase 5: Verify .gitignore
-1. Ensure `.gitignore` includes:
-- `public/assets/` (build artifacts)
-- `.DS_Store` (already present)
-- `*.code-workspace` (already present)
-- `dist/` (already present)
-## Files to Modify
-### Delete
-- `CLAUDE.md`
-- `SETUP_INSTRUCTIONS.md`
-- `public/assets/main-Byj9Aczh.css` (from git)
-- `public/assets/main-CNxY3Wx_.js` (from git)
-- `.DS_Store` (from git, multiple locations)
-- `neotoma.code-workspace` (from git)
-### Move
-- `scripts/README_RELEASE_ORCHESTRATOR.md` → `docs/developer/release_orchestrator.md`
-- `scripts/worker_agent_template.md` → `docs/feature_units/standards/worker_agent_template.md`
-### Update
-- `.gitignore` - Add `public/assets/` if not present
-- Any documentation files that reference moved files
-## Verification Steps
-1. Run `git status` to verify files are untracked/removed
-2. Verify `.gitignore` properly excludes build artifacts
-3. Check that moved documentation files are accessible in new locations
-4. Verify no broken references exist after moves
-5. Confirm build still works (artifacts regenerate in public/assets/)
-## Notes
-- Build artifacts in `public/assets/` should be regenerated by running the build process, not committed
-- The `public/` directory structure should remain, but `public/assets/` contents should be gitignored
-- Script documentation belongs in docs/ rather than scripts/ directory for better discoverability