docs: add ai-memory layer (bug patterns, architecture, debugging playbook, agent notes, initial failure archive)

ai-memory/bug-patterns.md

@@ -0,0 +1,117 @@
+# Bug Patterns — AITBC Repository
+
+This document records known bug patterns and their fixes to prevent reoccurrence.
+
+---
+
+## Pattern: Service Import Name Shadowing in CLI
+
+**Symptom**
+```
+KeyError: slice(None, 1, None)
+```
+or similar when invoking a CLI command that calls a service function.
+
+**Root Cause**
+CLI command modules import a service function (e.g., `generate_sar`) and then define a Click command function with the same name. The command function overwrites the imported service reference, causing the command body to call itself or the Click object instead of the service.
+
+**Typical Code**
+```python
+from regulatory_reporting import generate_sar  # <-- import
+
+@click.command()
+def generate_sar(...):  # <-- name collision! Overwrites the import
+    ...
+    result = generate_sar(...)  # BAD: now refers to this function, not the service
+```
+
+**Fix**
+Rename the imported function using an alias (e.g., `_svc` suffix) and update all internal calls.
+
+```python
+from regulatory_reporting import generate_sar as generate_sar_svc
+
+@click.command()
+def generate_sar(...):
+    ...
+    result = generate_sar_svc(...)  # GOOD: calls the actual service
+```
+
+**Files Affected**
+- `cli/aitbc_cli/commands/regulatory.py` (primary example)
+
+**Prevention**
+- Use consistent import aliasing when names might clash.
+- Consider naming CLI commands with a verb prefix (e.g., `cmd_generate_sar`) to avoid collision.
+- Static analysis could flag functions that shadow imported names.
+
+---
+
+## Pattern: Missing Service Dependencies in CLI Venv
+
+**Symptom**
+```
+ModuleNotFoundError: No module named 'numpy'
+```
+or similar when running CLI commands that import service modules.
+
+**Root Cause**
+CLI virtualenv lacks packages required by coordinator-api service modules (e.g., numpy, pandas, aiohttp, fastapi, uvicorn). The service modules are imported by CLI commands but their dependencies are not listed in the CLI's `pyproject.toml`.
+
+**Fix**
+Add the missing dependencies to the CLI package dependencies and reinstall.
+
+```toml
+dependencies = [
+    # existing...
+    "numpy>=1.26.0",
+    "pandas>=2.0.0",
+    "aiohttp>=3.9.0",
+    "fastapi>=0.111.0",
+    "uvicorn[standard]>=0.30.0"
+]
+```
+
+Then:
+```bash
+pip install -e ./cli
+```
+
+**Files Affected**
+- `pyproject.toml` (root)
+- CLI virtualenv (`cli_venv/`)
+
+**Prevention**
+- Keep service module dependencies in a shared location or explicitly list them in CLI deps.
+- Run import tests in CI to catch missing deps early.
+
+---
+
+## Pattern: Brother Chain Not Producing Blocks
+
+**Symptom**
+Chain height stays at 0, transactions (e.g., mintFaucet) not confirmed.
+
+**Root Cause**
+PoA proposer not defined as authority in the consensus configuration, or no node is acting as the authorized proposer.
+
+**Fix**
+Ensure the genesis configuration includes the proposer as an authority and that the node's `.env` matches:
+- `PROPOSER_ID` and `PROPOSER_KEY` set
+- `CHAIN_ID` matches the genesis file
+- Node started with proper PYTHONPATH
+
+If still not producing, check logs for authority registration and consider creating a manual block or restarting with a proper genesis that includes the proposer.
+
+**Related Files**
+- `apps/blockchain-node/src/aitbc_chain/consensus/poa.py`
+- `.env` for brother node
+- Genesis YAML file
+
+**Prevention**
+- Provide a helper script to initialize a PoA chain with a single proposer for devnets.
+- Document the proposer setup clearly.
+
+---
+
+*End of bug patterns.*