git:20261012.2680ed3 to git:20261014.19c5364

1 added, 1 removed. Audit A to A.

# Strada.Brain

AI-powered Unity development assistant for Strada.Core framework projects. Multi-channel (Web, Telegram, Discord, Slack, CLI, Teams), multi-provider (OpenAI, Anthropic, Google, Groq, Ollama, OpenRouter), with autonomous learning and memory.

## Build & Test

```bash

npm install # Install dependencies

npm run bootstrap # Install + build web portal

npm run dev # Development mode (tsx watch)

npm test # Run all tests (batched vitest)

npm run test:portal # Run web portal tests

npm run doctor # Diagnose setup issues

```

- Node.js 20+ required, ESM modules (`"type": "module"`)

- Test runner: Vitest with batched execution via `scripts/run-vitest-batches.mjs`

- Web portal: React + Vite in `web-portal/`, builds to `src/channels/web/static/`

- TypeScript strict mode, Zod for config validation

## Architecture Overview

- Entry: `src/index.ts` (Commander CLI) → `src/core/bootstrap.ts`

- Agent loop: `src/agents/` — Orchestrator (~5K lines) + ~30 helper modules (reflection, intervention pipeline, end-turn, session, consensus, tool execution, loop shared, autonomy tracker, etc.)

- Shared agent utils: `src/agent-core/`

- 6 channel adapters: `src/channels/{web,telegram,discord,slack,cli,teams}/`

- Config: `src/config/` — Zod-validated, 90+ env vars

- Memory: `src/memory/` — AgentDB (SQLite + HNSW vectors), 3-tier auto-tiering

- Learning: `src/learning/` — event-driven pipeline, instinct lifecycle

- Goals: `src/goals/` — DAG decomposition, wave-based parallel execution

- Campaigns: `src/campaign/` — "GDD/idea in → finished game out": milestone ladder planning, single GDD approval gate, sprint auto-advance on task events, SQLite persistence with boot resume

- Local assets: `src/assets-local/` — free open-weights generation tier: device-gated model catalog (TripoSR 3D, SD1.5/SDXL/FLUX 2D), isolated Python venv runner (subprocess), procedural generators as the always-works floor; cloud providers optional, never required

- Security: `src/security/` — input sanitization, autonomy levels, permissions

- Dashboard: `src/dashboard/` — real-time WebSocket monitoring

- Web portal: `web-portal/` — React + Vite (separate package.json)

### Key Patterns

- **PAOR Loop**: Plan → Act → Observe → Reflect — the core agent execution cycle in the orchestrator

- **Modular Decomposition**: Orchestrator delegates to 16 focused modules; bootstrap delegates to bootstrap-providers, bootstrap-memory, bootstrap-channels, bootstrap-wiring

- **TypedEventBus**: All subsystem communication is event-driven

- **Channel Isolation**: Each channel adapter implements a common interface, sessions are isolated per-channel

- **Provider Agnostic**: LLM calls go through a unified provider layer supporting 6+ providers

## Codebase Memory Vault

When `config.vault.enabled=true`, the **Codebase Memory Vault** is how agents should search the codebase — do not re-read files per request. The vault provides persistent hybrid (BM25 + vector) and symbolic (PPR over a call/import graph) retrieval backed by SQLite (`<project>/.strada/vault/index.db`), auto-maintained by a chokidar watcher, a write-hook, and manual sync.

- Use `vault_init` to attach a project path and build its vault

- Use `vault_sync` to force a full reindex after large external changes

- Use `vault_status` to confirm a vault is healthy and up to date before relying on its results

**SelfVault** is bootstrapped automatically at startup and indexes Strada.Brain's own source (`src/`, `web-portal/src/`, `tests/`, `docs/`, `AGENTS.md`, `CLAUDE.md`), so agents can search their own code with the same tools. Prefer vault queries over repeated `Read`/`Grep` cycles on the same files. See [docs/vault.md](docs/vault.md) for the full reference.

## Code Style & Conventions

- TypeScript strict mode, ESM imports only (no CommonJS `require`)

- Zod schemas for all configuration and external data validation

- Prefer functional patterns; classes only for stateful components (Orchestrator, AgentManager)

- File naming: `kebab-case.ts` for source, `kebab-case.test.ts` for tests

- Test files live next to their source files, not in a separate directory

- No `any` types — use `unknown` with type guards when type is uncertain

- Prefer `interface` for object shapes, `type` for unions/intersections

- All public functions must handle errors — no unhandled promise rejections

- Max function length: keep functions focused and under ~50 lines where possible

## Git Workflow

- Branch naming: `feat/`, `fix/`, `refactor/`, `test/`, `docs/` prefixes

- Commit messages: `type(scope): description` format (e.g., `feat(agents): add delegation tool`)

- Never commit `.env`, credentials, or secrets

- Never force-push to `main`

- Prefer atomic commits — one logical change per commit

## Security

- Never hardcode API keys, secrets, or credentials

- All file paths must be sanitized against directory traversal

- Path containment checks must use `path.sep` (not hardcoded `"/"`), and absolute path detection must use `path.isAbsolute()` (not `startsWith("/")`) for Windows compatibility

- Spawning `.cmd` files on Windows requires `shell: true` (Node.js 22+, CVE-2024-27980)

- User input validated at system boundaries using Zod schemas

- Listeners bind `127.0.0.1` by default; `BIND_HOST` is the only way to widen that (validated, containers set `0.0.0.0`)

- Media processing includes SSRF protection and magic byte validation

- Prompt injection sanitization in memory and personality systems

## Boundaries

- Do NOT modify `node_modules/` or generated `dist/` files

- Do NOT create files in the project root

- Do NOT modify test infrastructure (`scripts/run-vitest-batches.mjs`)

- Do NOT add new npm dependencies — the project maintains a minimal dependency policy

- Do NOT skip or disable existing tests to make new code pass

- - Do NOT name a product a run was measured on, quote its design document, or commit its campaign export — not in code, comments, tests, fixtures, docs or commit messages. Write "the test game" and invented data; real exports and the vehicle's term list belong in the gitignored `tests/fixtures/local/` (`src/universality.test.ts` enforces this)

+ - Do NOT name, quote or commit material from any external project Strada.Brain was run against (names, design documents, campaign exports, measured counts or run ids) — not in code, comments, tests, fixtures, docs or commit messages. Fixtures and examples use invented data from an unrelated domain, and patterns, keyword lists and defaults are written for any project, never tuned to one document's wording or one product's look. Local lists of protected terms or confidential documents, if you keep them, live in the gitignored `tests/fixtures/local/*.txt`; `src/universality.test.ts` checks every publishable file against them and skips with a stated reason when they are absent

- Channel-specific code stays in its own `src/channels/{name}/` directory

- Core orchestrator changes require careful review — it coordinates the entire agent lifecycle