YBIS_Dev - Autonomous Software Factory (Tier 4.5)

Tier 4.5 Autonomous System: AI agents managing self-evolution through SQLite, Pydantic, and Git.

---

NEW AI Agent? Start Here

Read this first: AGENTS.md - Single source of truth for entry point and quick start
Then read: docs/AI_START_HERE.md - Detailed onboarding guide
Architecture: docs/ARCHITECTURE.md - System architecture
Bootstrap: docs/BOOTSTRAP_PLAN.md - Implementation order

Quick Start:

# One-command setup
./scripts/bootstrap.sh        # Linux/Mac
.\scripts\bootstrap.ps1        # Windows

# Run a task
python scripts/ybis_run.py TASK-123

---

Current Phase: Tier 4.5 "The Great Stabilization" → New Architecture Migration

Status: CANONICAL = src/ybis/ (legacy src/agentic/ is deprecated)
Goal: Self-sustaining autonomous production with Git-based cleanup and SQLite persistence.

New Architecture (In Progress):

• Evidence-first governance: All runs produce verifier_report.json and gate_report.json
• Syscalls-only mutation: All file/exec operations go through src/ybis/syscalls/
• Immutable runs: workspaces/<task_id>/runs/<run_id>/ structure
• Deterministic gates: Policy snapshot + evidence = decisions

---

📜 Governance

New Constitution: docs/CONSTITUTION.md - Non-negotiables for new architecture Legacy Constitution: docs/governance/YBIS_CONSTITUTION.md - Original governance

Key principles:

• Canonical execution: scripts/ybis_run.py TASK-123 for single tasks; scripts/ybis_worker.py for background processing
• Evidence-first governance: All runs produce verifier_report.json and gate_report.json
• Syscalls-only mutation: All file/exec operations go through src/ybis/syscalls/
• Immutable runs: workspaces/<task_id>/runs/<run_id>/ structure
• Legacy is deprecated: src/agentic/ remains for reference only

Quick Start:

# Run a task
python scripts/ybis_run.py TASK-123

# Or run background worker
python scripts/ybis_worker.py

See also: docs/specs/GOVERNANCE_ACTION_PLAN.md

---

Architecture: The Orchestration Engine

Legacy Architecture (Deprecated)

Protocol-based plugin architecture powered by LangGraph:

1. The Brain (Workflow): src/agentic/core/graphs/orchestrator_graph.py - Manages state transitions.
2. The Executor (AiderEnhanced): Advanced code generation with constitutional enforcement.
3. The Verifier (SentinelEnhanced): High-security gates with AST analysis and isolated testing.
4. The Janitor (GitManager): Automatic atomic commits for every successful task.
5. The Persistence (SQLite): Thread-safe async task management via aiosqlite.

New Architecture (Target)

Evidence-first governed agent runtime:

1. Contracts: src/ybis/contracts/ - Pydantic models with schema_version
2. Syscalls: src/ybis/syscalls/ - Single enforcement point (fs, exec, git, approvals)
3. Control-plane: src/ybis/control_plane/ - DB operations (tasks, runs, leases, workers)
4. Data-plane: src/ybis/data_plane/ - Evidence artifacts, journals, approvals
5. Orchestrator: src/ybis/orchestrator/ - LangGraph workflows + deterministic gates
6. Adapters: src/ybis/adapters/ - Third-party integrations (Aider, OpenHands, etc.)
7. Services: src/ybis/services/ - MCP server, worker runtime
8. Migrations: src/ybis/migrations/ - Schema versioning

References:

• docs/ARCHITECTURE.md - Full architecture details
• docs/INTERFACES.md - Contracts, syscalls, MCP tools
• docs/WORKFLOWS.md - LangGraph routing and workflows
• docs/BOOTSTRAP_PLAN.md - Implementation task order

---

Roadmap & Tiers

Tier 4: The Sentinel (Completed)

• Capability: Automatic maintenance, Git-driven cleanup, and Pydantic validation.
• Status: Stable.

Tier 4.5: New Architecture Migration (CURRENT)

• Goal: Migrate to evidence-first, syscalls-only, deterministic gates architecture
• Status: In progress - following docs/BOOTSTRAP_PLAN.md

Tier 5: Self-Architecture (NEXT)

• Goal: Agents designing and modifying the factory's own graph nodes.
• Concept: Architect agents using SDD (Spec-Driven Development) to mutate the system.

---

Directory Structure

Legacy Structure (Deprecated, reference-only)

YBIS_Dev/
├── legacy/                        # Legacy code (read-only reference)
│
├── src/agentic/                   # Legacy structure (deprecated)
│   ├── core/config.py            # Path Configuration
│   ├── core/graphs/orchestrator_graph.py # The Brain (LangGraph)
│   └── core/protocols.py         # Data Contracts (Pydantic)
│
├── platform_data/knowledge/
│   └── LocalDB/tasks.db        # Task Database
│
├── AI_START_HERE.md              # Agent onboarding (legacy)
├── SYSTEM_STATE.md               # Complete system state
└── README.md                     # This file

New Structure (Target)

YBIS_Dev/
├── src/ybis/                     # New platform core
│   ├── contracts/                 # Pydantic models
│   ├── syscalls/                  # Enforcement point
│   ├── control_plane/              # DB operations
│   ├── data_plane/                # Evidence artifacts
│   ├── orchestrator/              # LangGraph + gates
│   ├── adapters/                  # Third-party integrations
│   ├── services/                  # MCP server, worker
│   └── migrations/                # Schema versioning
│
├── configs/profiles/              # Policy profiles
│   ├── default.yaml
│   └── strict.yaml
│
├── workspaces/                    # Immutable runs
│   └── <task_id>/
│       └── runs/
│           └── <run_id>/
│               ├── artifacts/     # verifier_report.json, gate_report.json
│               └── journal/       # events.jsonl
│
├── docs/                          # Canonical documentation
│   ├── CONSTITUTION.md
│   ├── ARCHITECTURE.md
│   ├── INTERFACES.md
│   ├── WORKFLOWS.md
│   ├── BOOTSTRAP_PLAN.md
│   └── ...
│
├── AGENTS.md                      # Agent entry point
└── README.md                      # This file

---

Visualization & Monitoring

Graph View:

• Neo4j Browser: http://localhost:7474 - Graph database browser
• PROJECT NEO Visualization: http://localhost:3000 - Interactive graph visualization (Sigma.js)
• Dashboard: http://localhost:8501 - Streamlit dashboard with system health

References:

• docs/specs/PROJECT_NEO_VIZ.md - Visualization strategy
• src/dashboard/viz/ - React/TypeScript visualization frontend
• src/dashboard/app.py - Streamlit dashboard

---

Last Updated: 2025-01-XX
System Version: 4.5.0 (Tier 4 Stable) → 0.1.0 (New Architecture)
System Integrity: 100% (Legacy) | Migration in progress (New)