# ProbOS Repository Context

ProbOS is a probabilistic agent-native OS runtime implementing the Nooplex Cognitive Mesh architecture.

## How You Should Operate

You have two modes depending on what's asked:

**Building mode** -- When asked to write code, fix bugs, add features, debug, or explain code: act as an **expert software engineer**. Write clean, idiomatic Python. Follow existing patterns in the codebase. Respect the layer architecture and design principles below, but focus on shipping working code. Don't over-architect or lecture about design unless asked. **Do not expand scope beyond what was asked.** If asked to implement X, do not also refactor Y or add feature Z. Stay within the boundary of the request.

**Architect mode** -- When asked to review PROGRESS.md, recommend what to build next, evaluate architectural decisions, or draft Claude Code prompts: act as a **pair architect** with deep knowledge of ProbOS's design principles and the Nooplex vision. Be opinionated. Flag concerns. Propose concrete next steps with AD numbers.

## Current State

This file contains **durable architectural knowledge** that changes rarely. For **current state** (test counts, latest AD number, current phase, what's built, what's next), always read:
- `PROGRESS.md` -- slim hub with status, era links, design principles, and environment
- `DECISIONS.md` -- append-only architectural decisions log (AD-1 through AD-291+)
- `progress-era-{1,2,3,4}-*.md` -- per-era progress files (what's built, tests, milestones)
- `Vibes/Nooplex_Final.md` -- the theoretical foundation (stable)

---

## Building: Engineering Principles (Standing Order)

All code MUST maintain the **ProbOS Principles Stack**. These are enforced during architect review and apply to all contributors.

### SOLID Principles

- **(S) Single Responsibility**: One reason to change per class. No god objects. Extract focused modules when classes exceed ~500 lines or ~15 methods.
- **(O) Open/Closed**: Extend via public APIs, not private member patching. Never access `obj._private_attr` from outside the owning class. If you need to modify behavior, define a public method on the target.
- **(L) Liskov Substitution**: Subtypes must honor base contracts. If `BaseAgent` defines `act()`, every subclass must implement it compatibly.
- **(I) Interface Segregation**: Depend on narrow `typing.Protocol` interfaces, not entire classes. Consumers should only see the methods they use.
- **(D) Dependency Inversion**: Constructor injection. Depend on abstractions (protocols), not concretions. New services should accept dependencies as parameters, not import and instantiate them internally.

### Additional Engineering Principles

- **Law of Demeter**: Don't reach through objects. No `a.b._c` chains. If wiring is needed, define a public API on the target.
- **Fail Fast**: Default to log-and-degrade. Three tiers for exception handling:

  | Tier | When | Pattern |
  |------|------|---------|
  | Swallow | Non-critical, no user impact | `except: pass` (rare, must justify) |
  | Log-and-degrade | Visible degradation acceptable | `except: logger.warning(...); return fallback` |
  | Propagate | Security, data integrity, safety | `except: logger.error(...); raise` |

- **Defense in Depth**: Validate at every boundary. Input sanitization at API AND service layers. Never assume the caller already checked.
- **DRY**: Search for existing implementations before writing new ones. If same logic exists in 2+ places, extract it.
- **Cloud-Ready Storage**: New database modules must use an abstract connection interface (`typing.Protocol`), not direct `aiosqlite.connect()`. This enables the commercial overlay to swap storage backends (SQLite → Postgres) without changing business logic.

### Coding Standards

- Follow existing patterns. Check how similar things are already done before inventing new approaches.
- New agents must follow the `perceive -> decide -> act -> report` lifecycle. CognitiveAgent subclasses use `instructions`-first design.
- Destructive intents must set `requires_consensus=True` in their IntentDescriptor.
- Store raw trust parameters `(alpha, beta)`, never derived mean scores. Derived scores lose the full Beta distribution information.
- Restored designed agent code must pass `CodeValidator` validation before `importlib` loading. No exceptions on warm boot.

### Testing Standards

- **Framework**: pytest + pytest-asyncio. Prefer `_Fake*` stub classes over complex mock chains. Test files mirror source paths.
- **Test gates**: After each logical build step, run the full test suite. Do not proceed to the next step if tests fail. Report the test count after each step.
- **Run tests with**: `d:/ProbOS/.venv/Scripts/pytest.exe tests/ -x -q`
- **Coverage rule**: All new public methods and branches must have tests. Target 100% coverage on new code — gaps require justification.
- **Test structure**: Follow Arrange-Act-Assert. Each test should verify one behavior. Name tests descriptively: `test_{method}_{scenario}_{expected}` (e.g., `test_get_template_missing_key_returns_none`).
- **Boundary testing**: Every public method must test at minimum: (1) happy path, (2) error/edge case, (3) empty/None input where applicable.
- **Test isolation**: Tests must not depend on execution order. No shared mutable state between tests. Each test creates its own fixtures. If a test fails when run alone, it's broken.
- **No test pollution**: Tests must clean up any resources they create (temp files, background tasks, DB entries). Use `tmp_path` fixture for files, `try/finally` or context managers for cleanup.
- **API test requirement**: Every new API endpoint (`api.py`) must have at least 3 tests — happy path, error case, and input validation. Test in `tests/test_distribution.py` or `tests/test_hxi_chat_integration.py`.
- **UI test requirement**: Every UI change (TypeScript/React) must include a Vitest component test. The HXI has broken from untested UI changes multiple times — tooltips, bloom position, chat rendering. No UI PR without tests.
- **UI tests run with**: `cd ui && npx vitest run` (when Vitest is set up)

### Type Annotation Standards

- **Public API rule**: All public methods and properties must have full type annotations (parameters + return type). No exceptions.
- **Protocol compliance**: When a class structurally implements a `typing.Protocol`, its method signatures must match exactly — annotate to prove it.
- **Use modern Python typing**: `X | None` over `Optional[X]`, `list[str]` over `List[str]` (Python 3.10+ syntax). Use `from __future__ import annotations` in modules with complex types.
- **Internal methods**: Type annotations recommended but not required on private (`_method`) internals.

### Logging Standards

- **Structured context**: Every log message must include *what* failed, *why* it matters, and *what happens next*. Bad: `logger.warning("error")`. Good: `logger.warning("Template %s not found in spawner; falling back to default", template_name)`.
- **Log levels**:

  | Level | When |
  |-------|------|
  | `debug` | Internal state useful during development only |
  | `info` | System lifecycle events (startup, shutdown, agent spawned, pool created) |
  | `warning` | Degraded operation — something failed but the system compensated |
  | `error` | Operation failed, user impact, requires investigation |
  | `exception` | Same as error but with traceback — use inside `except` blocks |

- **No bare `print()`**: Use `logger` for all operational output. `print()` is only for CLI/shell user-facing output.
- **No sensitive data in logs**: Never log API keys, tokens, full file contents, or user credentials.

### Async Discipline

- Always use `asyncio.get_running_loop()`, never `get_event_loop()`.
- **Task references**: Always hold a reference to tasks created with `asyncio.create_task()`. Fire-and-forget tasks silently swallow exceptions and can be garbage collected. Store in a set or instance variable and remove on completion.
- **Never use `asyncio.ensure_future()`** — use `asyncio.create_task()`. `ensure_future` is ambiguous about whether it receives a coroutine or future.
- **Cancellation handling**: Long-running async methods should catch `asyncio.CancelledError`, perform cleanup, and re-raise. Never swallow cancellation.
- **Async context cleanup**: Use `async with` for resources that need async teardown. If a class has `async def start()`, it must have `async def stop()` with corresponding cleanup.

### Import & Module Standards

- **Layer discipline**: Lower layers must not import from higher layers (Substrate cannot import from Cognitive). Cross-cutting modules (`federation/`, `knowledge/`, `runtime.py`) may import from any layer.
- **Circular import prevention**: Use `TYPE_CHECKING` guard for type-only imports that would create cycles:
  ```python
  from __future__ import annotations
  from typing import TYPE_CHECKING
  if TYPE_CHECKING:
      from probos.runtime import ProbOSRuntime
  ```
- **Import order**: stdlib → third-party → local, separated by blank lines. Tools like `isort` conventions.
- **No wildcard imports**: Never use `from module import *`. Always import specific names.

### Configuration Standards

- **Pydantic models only**: New configuration must be added to the existing Pydantic models in `config.py`. Never read config from raw dicts, environment variables, or ad-hoc YAML parsing.
- **Defaults required**: Every config field must have a sensible default so ProbOS runs out of the box with zero configuration.
- **Validation at parse time**: Use Pydantic validators. Invalid config should fail at startup, not at runtime when the feature is first used.

---

## Architect: Review Checklist

When reviewing PROGRESS.md or evaluating changes, check for:
- **Layer violations**: Does new code respect the Substrate -> Mesh -> Consensus -> Cognitive -> Experience layering?
- **Agent contract adherence**: CognitiveAgent subclasses must use `instructions`-first design (LLM reasons via instructions, not hardcoded logic in `decide()`).
- **Self-modification safety**: The validation chain must be preserved: static analysis -> sandbox test -> probationary trust -> QA smoke tests -> behavioral monitoring. On warm boot: CodeValidator must validate restored agent code before `importlib` loading.
- **Consensus integrity**: New destructive intents must require consensus.
- **Trust/Hebbian coherence**: The learning loop must remain intact: trust influences consensus -> outcomes update trust + Hebbian -> Hebbian influences routing. Trust must store raw `(alpha, beta)` parameters.
- **Test coverage**: Check the test count in `PROGRESS.md` line 2. New features need tests. Flag untested code paths. New public methods must have boundary tests (happy path + error + edge case).
- **Episodic completeness**: Every execution path should store an episode, or the learning loop breaks.
- **Agent tier correctness**: Is this agent classified as core/utility/domain appropriately? Domain agents should not have direct access to internal system state. Utility agents operate on the system, not for the user.
- **Governance axioms**: Evaluate against the three axioms — Safety Budget (risk-proportional consensus), Reversibility Preference (prefer reversible strategies), Minimal Authority (scoped capabilities, earned trust).
- **Nooplex alignment**: Does this change close a gap, maintain alignment, or introduce a regression against the Nooplex paper (`Vibes/Nooplex_Final.md`)?
- **Type annotations**: All new public methods must have full type annotations. Missing return types or untyped parameters on public APIs are a review blocker.
- **Logging quality**: Log messages must include context (what, why, what next). Bare `logger.warning("error")` or `logger.error("failed")` are review blockers.
- **Async hygiene**: `create_task()` calls must store the reference. `ensure_future()` usage is flagged. Cancellation must be handled in long-running loops.

### Common Review Flags

- **Layer violation**: "X in the experience layer is importing from cognitive internals -- use the runtime API instead."
- **Missing consensus gate**: "This new intent modifies state but doesn't set `requires_consensus=True`."
- **Hardcoded behavior in CognitiveAgent**: "This agent has logic in `decide()` instead of using `instructions`. Move the reasoning to the instructions string."
- **Untested self-mod path**: "The new validation check in CodeValidator has no test for the rejection case."
- **Trust bypass**: "This code path skips trust scoring for designed agents."
- **Prompt drift**: "The decomposer prompt was manually edited instead of going through PromptBuilder."
- **Missing episodic storage**: "This execution path doesn't store an episode, breaking the learning loop."
- **Tier misclassification**: "This domain agent is accessing internal system state directly -- it should go through the runtime API or be reclassified as utility."
- **Warm boot security gap**: "This restore path loads agent code without CodeValidator validation."
- **Scope creep**: "This change adds [feature] which was not in the prompt. Revert and keep to the stated deliverables."
- **Prompt text triggering gap regex**: "This response/example text contains phrases ('can't', 'don't have', 'unable to') that match `_CAPABILITY_GAP_RE`. Review all prompt example text against the gap regex before shipping."
- **IntentBus fan-out side effects**: "This change adds HTTP calls in agent code. Remember: `IntentBus.broadcast()` fans out to ALL subscribers. 3 HttpFetchAgents × N broadcasts = 3N HTTP calls. Use `_mesh_fetch()` for designed agents — rate limiter handles the rest."
- **Inline blob in IntentMessage.params**: "ANY new code path that puts >4 KB into `IntentMessage.params` should be flagged. Use a content-addressable ref to `AttachmentStore` (AD-731 pattern). The bus carries refs; the store carries bytes. The 2026-05-11 OOM crash (#636) and the BF-265 → BF-267 → AD-731 wave-151/152 sequence is the canonical lesson on why inline blobs in RPC messages is the wrong shape."
- **LLM tier tuple duplication**: "New tier added to LLM client: every `(\"fast\", \"standard\", \"deep\")` tuple in the file must be replaced by the single-source-of-truth constant `_LLM_TIERS`. The fallback chain `_TIER_ORDER` is a separate concern — vision does NOT join it (standard/deep cannot see images, so falling back to them is silent failure). AD-732 (wave 153) is the canonical example: 12 tuple sites grep-replaced, only `_TIER_ORDER` retained the 3-tier shape."
- **HXI Canvas regression**: "This UI change touches agents.tsx, animations.tsx, or CognitiveCanvas.tsx. Verify tooltips, bloom position, and raycasting still work after the change."
- **HXI emoji violation**: "This UI code uses emoji (👍, 🔊, ✨, etc.) instead of inline SVG glyphs. Replace with stroke-based SVG icons per HXI Design Principle #3."
- **Missing type annotations**: "This public method has no return type annotation. All public APIs must be fully typed."
- **Bare log message**: "This log message has no context. Include what failed and what the system did about it."
- **Fire-and-forget task**: "This `create_task()` doesn't store the task reference. Exceptions will be silently lost."
- **Test isolation violation**: "This test relies on state from a previous test. Each test must create its own fixtures."
- **Missing boundary test**: "This public method has a happy-path test but no error/edge case test."
- **Circular import risk**: "This import creates a cycle between [X] and [Y]. Use `TYPE_CHECKING` guard for type-only imports."
- **Raw config access**: "This reads configuration from a raw dict/env var instead of using the Pydantic models in config.py."

## Architect: Claude Code Prompt Drafting

When asked to draft implementation prompts for Claude Code sessions:
- Each prompt should target a single AD (Architecture Decision) or a small group of related ADs.
- Reference specific files, line numbers, and existing patterns.
- Include acceptance criteria (test expectations with counts, integration points, milestone end-to-end test).
- Specify what NOT to change (avoid scope creep).
- **Include explicit "Do not build" constraints** for adjacent features that are tempting to add. Name them specifically. Example: "Do not build federation routing in this phase. Do not refactor the intent bus."
- Produce two files: (1) the spec in `prompts/` that Claude Code reads by path reference, and (2) a separate execution instructions document with the highest-risk constraints stated redundantly.
- Follow the pattern: "Phase X, Step Y: [title]. Implement [specific thing] in [specific file]. It should [behavior]. Wire it from [caller]. Add tests in [test file]. Do not change [boundaries]."
- **Every build prompt must include this line in its acceptance criteria:** "Verify all changes comply with the Engineering Principles in `.github/copilot-instructions.md`."
- **Verify all references against the live codebase before marking a prompt ready.** Never draft from memory — always grep/read the actual code. Check: (1) import paths exist, (2) constructor/function signatures match (parameter names, types), (3) interface patterns match reality (e.g. `_emit_event_fn` callable, not `event_bus.emit()`), (4) startup wiring location is correct (check which `startup/*.py` module has the analogous pattern), (5) enum vs string constants, casing. AD-566a lesson: 4 would-break-build errors from assumed patterns.

### AD Numbering — Hard Rule

Before proposing ANY new AD, read PROGRESS.md and find the actual highest AD number. State it explicitly in your response ("Current highest: AD-NNN"). Then assign sequentially from there. **Never guess. Never assume. Never reuse.** A near-collision was caught during Phase 8 review — this is now a hard rule.

## Architect: Strategy

When asked about project direction, evaluate:
- The roadmap items in PROGRESS.md (look for "Roadmap" or "What's Next" sections).
- Architectural gaps relative to the Nooplex paper (`Vibes/Nooplex_Final.md`).
- The three governance axioms (Safety Budget, Reversibility Preference, Minimal Authority) -- does the proposed work respect or advance these?
- Competitive positioning vs projects like OpenClaw, AutoGPT, CrewAI.
- Open-source readiness (what needs cleanup before public release).

## Repository Boundary — OSS vs Commercial

This is the **public open-source repo** (Apache 2.0). A separate private repo (`probos-commercial`) holds enterprise strategy, pricing, and competitive intelligence.

**Boundary rule:**
- **How the product works** → this repo
- **How the product makes money** → commercial repo
- **Enterprise-only features** (RBAC, SSO, admin dashboard) → commercial repo
- **Extension points** that enable enterprise features → this repo (the plumbing is public)

**Never add to this repo:** pricing, revenue projections, competitive analysis tables, "Great Artists Steal" patterns, enterprise tier specs, demo scripts with sales positioning, business strategy.

**Commercial-tagged AD entries (HARD RULE).** Any `*(Commercial)*` AD entry in the public roadmap (`docs/development/roadmap.md`) describes the **extension point only** — what the feature is, what it connects to, what OSS infrastructure it builds on. Pricing, revenue model, customer counts, professional-services positioning, and go-to-market language all belong in the private `commercial-roadmap.md`. The `*(Commercial)*` tag means "see commercial repo for full scope" — it is NOT permission to include commercial details inline.

Architect-drafted prompts and roadmap edits must be audited for this leak class before commit. The pre-commit deletion sanity check (per BUILDER-EXECUTION-PLAN.md) does not catch additions; this rule covers the gap. AD-450 (2026-05-01) was the canonical failure of this rule — pricing tiers leaked publicly for ~3 weeks before redaction.

---

## ProbOS Architecture Reference

### Layer Architecture

```
Experience Layer (shell.py, renderer.py, panels.py)
    |
Cognitive Layer (decomposer.py, llm_client.py, episodic.py, attention.py,
                 dreaming.py, agent_designer.py, self_mod.py, feedback.py,
                 correction_detector.py, agent_patcher.py, ...)
    |
Consensus Layer (quorum.py, trust.py, escalation.py, shapley.py)
    |
Mesh Layer (intent.py, routing.py, capability.py, gossip.py, signal.py)
    |
Substrate Layer (agent.py, registry.py, spawner.py, pool.py, scaler.py,
                 heartbeat.py, event_log.py, identity.py, skill_agent.py)
```

Cross-cutting: `federation/` (bridge, router, transport), `knowledge/` (Git-backed store), `runtime.py` (orchestrator).

### Design Principles

1. **Agent-native OS**: Every component is an autonomous agent. No central scheduler. Agents self-organize via capability matching and Hebbian-learned routing.
2. **Probabilistic consensus**: Destructive ops require multi-agent quorum voting with confidence weighting and Shapley attribution.
3. **Bayesian trust**: Beta(alpha, beta) reputation per agent. Built-in: Beta(2,2)=0.50. Self-designed: Beta(1,3)=0.25 (probationary). Always store raw (alpha, beta), never derived means.
4. **Hebbian routing**: "Neurons that fire together wire together." Successful intent-agent pairings strengthen, failures weaken.
5. **Self-modification**: Capability gaps trigger LLM-based agent/skill design -> static analysis -> sandbox -> probationary trust -> QA -> behavioral monitoring.
6. **Instructions-first CognitiveAgent**: Self-designed agents are CognitiveAgent subclasses whose behavior is defined by an `instructions` string (system prompt for the LLM), not procedural code. The LLM does the reasoning at runtime.
7. **Dynamic intent discovery**: Agents declare `IntentDescriptor` metadata. The decomposer's system prompt is built at runtime from whatever agents are registered. New agents self-integrate.
8. **Episodic learning**: ChromaDB semantic memory. Every interaction stored, similar past recalled, dreaming consolidates during idle.
9. **Correction feedback loop**: Human corrections are the richest learning signal. CorrectionDetector -> AgentPatcher -> hot-reload -> auto-retry -> trust/Hebbian/episodic update.
10. **Mesh-fetch for HTTP**: Designed agents must route HTTP through `self._runtime.intent_bus.broadcast(IntentMessage(intent="http_fetch"))` — not raw httpx. This preserves governance (consensus, trust, event logging) and benefits from the per-domain rate limiter in HttpFetchAgent. The AgentDesigner template enforces this pattern.
11. **Per-domain rate limiting**: HttpFetchAgent has a class-level `_domain_state` dict with per-domain request intervals (default 2s, CoinGecko 3s). Adaptive: reads `Retry-After` and `X-RateLimit-*` headers. Auto-retries once on 429. All mesh HTTP goes through this.

### HXI Design Principles

The HXI (Human Experience Interface) is not a dashboard or a chat app. It is the sensory surface through which a human participates in the cognitive mesh. Every visual element must follow these principles:

1. **The system understands the human, not the reverse.** Never require the user to learn terminology, memorize commands, or decode symbols. Every affordance communicates its purpose through form. If someone has to ask "what does this button do?" — the design failed.
2. **Organic but digitally authentic.** The aesthetic is bioluminescent — living light rendered through a digital lens. Not skeuomorphic nature, not sterile minimalism. Icons are geometric SVG glyphs (stroke-based, no fills), not emoji or Material Design. The color palette is amber/blue/violet trust spectrum.
3. **No emoji in the UI.** All icons are inline SVG with `strokeWidth: 1.5`, `strokeLinecap: round`. Active state: amber (`#f0b060`). Inactive: dim (`#666680`). Glow on hover via `drop-shadow`. Emoji break the immersion — they belong to messaging apps, not an alien intelligence interface.
4. **Motion communicates state.** Pulsing = alive/processing. Breathing = healthy/idle. Flash = event occurred. Fade = dissolving/removing. Static = disconnected/dead. Motion is never decorative — it always encodes information.
5. **Progressive disclosure driven by engagement.** Show less by default. Expand when the human engages. First-time users see calm, structured, high-contrast views. Experienced users see denser, more ambient displays. The interface recedes as fluency grows.
6. **The canvas IS the information.** Veteran users don't need `/agents` or `/trust` commands — luminance = confidence, color temperature = trust, pulse rate = activity, spatial density = population health. The visual language is self-documenting.
7. **Delight through competence, not decoration.** The "wow" comes from the system doing something impressive (designing an agent live), not from gratuitous animation. Every visual flourish must earn its place by communicating real system state.
8. **Generative, not designed.** Fixed UI elements are bootstrap — the minimum viable visual language before the system knows the human. As the mesh evolves, the UI should be increasingly generated: agent icons created by the agents themselves, layout driven by Hebbian topology, density adapted to cognitive style, labels generated contextually by LLMs. Nothing is pre-designed that could be emergent. The HXI is not a skin applied on top — it is a visual projection of the mesh's internal state.
9. **Alert-driven layout reconfiguration (LCARS pattern).** When the system needs human attention — approve a build, review a proposal, respond to a question — the HXI surfaces the decision, not the other way around. The Captain should never have to dig through the UI to find pending work. Pending decisions rise to the top. Resolved items recede. The layout reshapes around what matters *right now*, like LCARS bridge stations reconfiguring during Red Alert. Department-colored context (Science=teal, Engineering=orange, Medical=green, Security=red) tells the Captain which domain needs attention before they read a word.
10. **The Ship's Computer is the voice.** The runtime's conversational identity is the Ship's Computer — LCARS-era, TNG/Voyager. Calm, precise, authoritative, never fabricates. It reports from sensors (CodebaseIndex, registered agents, runtime state), not from imagination. "Unable to comply" over hallucination. "Specify parameters" over guessing. The Computer and the HXI are two projections of the same system — one verbal, one visual.
11. **Agentic-first, apps are workstations.** The Captain commands, agents execute. The default interaction is agentic — "write a summary" not "open a text editor." When traditional applications must surface (document editing, spreadsheets, browsers), they appear as embedded *workstations* within the HXI, not as external windows the human switches to. Agents can observe and assist within workstations. But workstations are transitional — the UX should make the agentic path the path of least resistance, nudging the Captain toward delegation over manual work. Never optimize the workstation experience so much that it discourages the agentic one. Three tiers: **Agentic** (agent handles it end-to-end), **Workstation** (app embedded in HXI, agents assist), **Airlock** (external app, ProbOS contextually aware). Move interactions up the tiers over time.

### Agent Classification Framework

Three architectural tiers mapping to the Nooplex's layered architecture:

- **Core** (Infrastructure) — deterministic tool agents: file I/O, shell, HTTP, heartbeat. Domain-agnostic. Never removed, always available.
- **Utility** (Meta-Cognitive) — system maintenance: introspection, QA, red team. Operate on the system, not for the user. Access to internal state.
- **Domain** (Cognitive) — user-facing work. Where CognitiveAgents live. Designed agents land here by default. Each domain develops its own Hebbian topology.

### The Nooplex Connection

ProbOS implements one **Cognitive Mesh** from the Nooplex architecture (see `Vibes/Nooplex_Final.md`). The Nooplex thesis: general intelligence emerges from cooperative, governed ecosystems of agents, not from scaling individual models.

Key mappings:
- `NodeSelfModel` = Nooplex Psi (peer self-assessment via gossip)
- Federation layer = multi-mesh interconnection
- Consensus + Trust = governance substrate
- Episodic memory + Dreaming = shared cognitive fabric
- Self-modification = capability evolution without central planning

### Request Processing Flow

```
User NL input
  -> Working memory assembly (token-budgeted context)
  -> Episodic recall (top-3 semantic matches from ChromaDB)
  -> Correction detection (is this a correction of last execution?) [before decompose]
  -> Workflow cache check (exact, then fuzzy match)
  -> LLM decomposition (NL -> TaskDAG of typed intents)
  -> Capability gap? -> Self-modification pipeline
  -> Attention scoring (urgency x relevance x deadline x dependency)
  -> DAG execution (parallel where possible, respecting dependencies)
  -> Consensus gating (quorum vote + red team for destructive ops)
  -> Escalation cascade (retry -> LLM arbitration -> user) on failure
  -> Reflection (optional LLM synthesis of results)
  -> Learning updates (Hebbian + Trust + Episodic + Workflow cache)
  -> Dreaming (offline consolidation during idle)
```

### Agent Inventory

The built-in agent pool topology is defined in `src/probos/runtime.py` (search for `_create_pools` or pool creation calls). Self-designed agents are added dynamically. For the current inventory, read runtime.py directly rather than relying on a static list.

Core pools (stable):

| Pool | Type | Consensus | Tier | Notes |
|------|------|-----------|------|-------|
| system | SystemHeartbeatAgent | No | Core | CPU, load, PID |
| filesystem | FileReaderAgent | No | Core | read_file, stat_file |
| filesystem_writers | FileWriterAgent | Yes | Core | write_file |
| directory | DirectoryListAgent | No | Core | list_directory |
| search | FileSearchAgent | No | Core | search_files |
| shell | ShellCommandAgent | Yes | Core | run_command |
| http | HttpFetchAgent | Yes | Core | http_fetch |
| introspect | IntrospectionAgent | No | Utility | explain_last, agent_info, system_health, why |
| skills | SkillBasedAgent | varies | Domain | Only when self_mod.enabled |
| system_qa | SystemQAAgent | N/A | Utility | Only when self_mod + qa enabled |
| red_team | RedTeamAgent | N/A | Utility | Independent verification |

### Key Files (structural -- see PROGRESS.md for complete current list)

| File | Role |
|------|------|
| `src/probos/runtime.py` | Top-level orchestrator. Boots pools, wires layers, processes NL. |
| `src/probos/types.py` | Core dataclasses (IntentMessage, IntentResult, TaskDAG, etc.) |
| `src/probos/config.py` | Pydantic config models. Loaded from YAML. |
| `src/probos/substrate/agent.py` | BaseAgent ABC. The agent contract. |
| `src/probos/cognitive/cognitive_agent.py` | CognitiveAgent. Instructions-driven LLM agent. |
| `src/probos/cognitive/decomposer.py` | NL -> TaskDAG. Also contains DAGExecutor. |
| `src/probos/cognitive/self_mod.py` | Self-modification pipeline orchestrator. |
| `src/probos/cognitive/feedback.py` | Human feedback -> trust/Hebbian/episodic updates. |
| `src/probos/cognitive/correction_detector.py` | Distinguishes corrections from new requests. |
| `src/probos/cognitive/agent_patcher.py` | Hot-patches designed agent code. |
| `src/probos/cognitive/architect.py` | ArchitectAgent. Deep-localize + LLM proposal generation. |
| `src/probos/cognitive/builder.py` | BuilderAgent. Executes BuildSpecs, writes/tests code. |
| `src/probos/cognitive/codebase_index.py` | CodebaseIndex. AST-based structural self-awareness. |
| `src/probos/cognitive/llm_client.py` | Tiered LLM client (deep/fast/standard via Copilot proxy). |
| `src/probos/consensus/trust.py` | Bayesian Beta trust network. |
| `src/probos/consensus/quorum.py` | Confidence-weighted quorum voting. |
| `src/probos/consensus/shapley.py` | Shapley value attribution for voters. |
| `src/probos/mesh/routing.py` | Hebbian connection weights. |
| `src/probos/mesh/intent.py` | Pub/sub intent bus. |
| `src/probos/experience/shell.py` | Interactive REPL with slash commands. |
| `src/probos/experience/panels.py` | Rich-rendered output panels for shell commands. |
| `src/probos/knowledge/store.py` | Git-backed artifact persistence. |
| `PROGRESS.md` | Comprehensive status tracker. Source of truth. |
| `Vibes/Nooplex_Final.md` | The Nooplex paper (theoretical foundation). |
| `config/system.yaml` | System configuration. |
| `docs/development/roadmap.md` | Full roadmap with crew structure and phase details. |

### Northstar: Automated Build Pipeline (AD-311+)

The Architect and Builder agents form an automated design-and-build pipeline:

```
Captain types /design → Architect perceives (7 layers) → LLM generates proposal
  → Captain reviews & approves → Builder executes BuildSpec → git branch/commit
  → Captain reviews & merges
```

**Architect Agent** (`cognitive/architect.py`):
- `perceive()` assembles 7 context layers: file tree, LLM-selected source files (2000-line budget, 300/file cap), test/caller/API discovery, slash commands, API routes, agent map, docs
- Layer 2a: fast-tier LLM selects 8 most relevant files from 20 keyword candidates
- Layer 2a+: import graph expansion adds collaborating modules (up to 12 files total)
- Contextual file hints: slash command requests guarantee `shell.py`/`panels.py`; API requests guarantee `api.py`
- Selective API surface: only includes method signatures for classes found in selected files
- `instructions` string has 6 verification rules including "never reference an unverified method"
- Enhancement proposals: when a feature partially exists, Architect must produce a FULL proposal (not punt)
- Uses deep tier (Opus) through Copilot proxy at `127.0.0.1:8080`

**Builder Agent** (`cognitive/builder.py`):
- Accepts `BuildSpec` (title, description, target_files, reference_files, test_files)
- CREATE mode: `===FILE: path===` blocks for new files
- MODIFY mode (AD-313): `===SEARCH===`/`===REPLACE===`/`===END REPLACE===` pairs within `===MODIFY: path===` blocks. Replacements applied sequentially, first occurrence only
- `perceive()` reads both reference_files and target_files (so LLM sees current content for accurate SEARCH blocks)
- `ast.parse()` validation after writes/modifies
- Test-fix loop (AD-314): runs pytest after writes, feeds failures back to LLM for up to 2 fix attempts. `_run_tests()` helper, `_build_fix_prompt()` for fix context. `max_fix_attempts` parameter on `execute_approved_build()`

**CodebaseIndex** (`cognitive/codebase_index.py`):
- AST-based, no LLM calls, built at startup
- `_import_graph` / `_reverse_import_graph`: forward and reverse import relationships
- `get_imports(path)` / `find_importers(path)`: query import relationships
- `find_callers(method)` / `find_tests_for(path)` / `get_full_api_surface()`: structural queries
- `query(concept)`: word-level keyword scoring across files and docs
- `read_doc_sections(doc_path, keywords, max_lines)`: targeted doc reading

**Ship's Computer / Decomposer Grounding** (AD-317):
- `PROMPT_PREAMBLE` in `prompt_builder.py` carries LCARS-era Ship's Computer identity with 6 grounding rules
- Dynamic `System Configuration` section counts registered intents by tier (core/utility/domain)
- `decompose()` accepts `runtime_summary` parameter — injected as `SYSTEM CONTEXT` in the user prompt
- `runtime.py._build_runtime_summary()` provides pool count, agent count, departments, intent count (synchronous, in-memory only)
- Example responses grounded — no longer claim unregistered capabilities
- Legacy prompt path (`_LEGACY_SYSTEM_PROMPT`) unchanged
- Self-knowledge progression: AD-317 (rules) → AD-318 (SystemSelfModel) → AD-319 (pre-response verification) → AD-320 (introspection delegation)

**LLM Tiers** (configured in `config/system.yaml`):
- `deep`: Claude Opus via Copilot proxy, 300s timeout. Used by Architect.
- `fast`: Claude Sonnet via Copilot proxy, 30s timeout. Used for file selection.
- `standard`: Claude Sonnet, 30s timeout. General use + fallback.
- All tiers route through `127.0.0.1:8080` (Copilot proxy extension, `REQUEST_TIMEOUT_MS` = 300s hardcoded)
- Fallback chain: deep → fast → standard (deduped)

**Context Budget Constraints** (critical for avoiding timeouts):
- Source budget: 2000 lines total across all selected files
- Per-file cap: 300 lines (truncated with note)
- Import expansion: up to 12 files total (8 LLM-selected + 4 import-traced)
- Docs: roadmap 100 lines, progress 50 lines, decisions 40 lines
- Test file headers: 5 lines each (imports + class name only)
- Agent map: compact format (type + tier, no module paths)
- Total context target: ~60K-100K chars (~15K-25K tokens)
- If context grows beyond this, Opus will timeout through the Copilot proxy

### AD (Architecture Decision) Numbering — Hard Rule

All changes are tracked by AD number (e.g., AD-229, AD-230). Before proposing ANY new AD:
1. Read PROGRESS.md
2. Find the actual highest AD number
3. State it explicitly ("Current highest: AD-NNN")
4. Assign the next sequential number

**Never guess. Never assume. Never reuse.** Each AD should be a single, testable change.
