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

ai-memory/failure-archive/cli-missing-dependencies.md

@@ -0,0 +1,36 @@
+# Failure Archive Entry
+
+## Issue
+CLI commands failed with `ModuleNotFoundError: No module named 'numpy'` (and similar for `pandas`, `aiohttp`, `fastapi`, `uvicorn`).
+
+## Attempt
+Multiple attempts to run CLI commands after sibling branch integration; observed import errors when commands tried to load service modules.
+
+## Approach
+Initially attempted to fix by adjusting `PYTHONPATH` manually and creating a virtualenv. Discovered that the CLI virtualenv did not include required scientific and web dependencies.
+
+## Root Cause
+The `aitbc-cli` package in `pyproject.toml` did not declare dependencies that the service modules require. The coordinator-api services import `numpy`, `pandas`, `aiohttp`, `fastapi`, and `uvicorn`, but these were not listed under the CLI package's dependencies, leading to import failures when the CLI imported service modules.
+
+## Resolution
+Added the following to root `pyproject.toml` dependencies:
+```toml
+numpy>=1.26.0
+pandas>=2.0.0
+aiohttp>=3.9.0
+fastapi>=0.111.0
+uvicorn[standard]>=0.30.0
+```
+Then reinstalled the CLI in editable mode: `pip install -e ./cli`.
+
+## Useful Artifacts
+- The list of required packages is now part of the canonical dependency set.
+- The fix allowed all CLI commands (`surveillance`, `ai_trading`, `advanced_analytics`, `regulatory`, `compliance`, `ai_surveillance`) to load successfully.
+
+## Prevention
+- Keep shared dependencies in a central `pyproject.toml` that covers both services and CLI.
+- Implement an import test in CI that verifies CLI commands can import without error.
+
+---
+
+*Archived on 2026-03-15.*

ai-memory/failure-archive/regulatory-shadowing-trap.md

@@ -0,0 +1,57 @@
+# Failure Archive Entry
+
+## Issue
+Related to PR #10 (aitbc1/fix-imports-docs) – initial attempt before fixing.
+
+## Attempt
+Branch: `aitbc1/fix-imports-docs` (first version)
+Author: aitbc1
+
+## Approach
+Fixed CLI import errors by adding `numpy`, `pandas`, `aiohttp`, `fastapi`, `uvicorn` to `pyproject.toml` and modifying `main.py` to conditionally import enterprise integration.
+
+Did not rename the shadowed functions in `regulatory.py`.
+
+## Failure Mode
+Running `aitbc regulatory test` resulted in:
+```
+KeyError: slice(None, 1, None)
+```
+
+The Click command function `generate_sar` was shadowing the imported `generate_sar` from `regulatory_reporting`. When the command body called `generate_sar(...)`, it actually invoked the command function recursively or accessed the Click command object's subscript, causing a crash.
+
+## Root Cause
+Name collision between imported service function and CLI command function.
+
+## Detection
+Reproduced by running the regulatory test command after the branch was merged into a local main. Failure trace showed the command function being called with wrong arguments.
+
+## Resolution
+Renamed imported functions in `regulatory.py` with `_svc` suffix:
+- `generate_sar` → `generate_sar_svc`
+- `generate_compliance_summary` → `generate_compliance_summary_svc`
+- `list_reports` → `list_reports_svc`
+
+Updated all internal calls accordingly.
+
+## Useful Artifacts
+- The pattern of shadowing is now documented in `ai-memory/bug-patterns.md`.
+- The fix (aliasing service imports) should be applied to any command module where names overlap.
+
+## Prevention
+- When writing CLI command groups, avoid naming command functions identically to any imported callables from service modules.
+- Consider static analysis rule: flag functions that define a name already imported at module scope.
+- Alternatively, always import service functions with a distinct suffix (e.g., `_svc`) as a coding standard.
+
+## Recommendation
+Future implementations of CLI commands should adopt the naming convention: service imports end with `_svc`. Example:
+```python
+from regulatory_reporting import generate_sar as generate_sar_svc
+...
+def generate_sar(...):
+    return generate_sar_svc(...)
+```
+
+---
+
+*Archived on 2026-03-15.*