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

ai-memory/agent-notes.md

@@ -0,0 +1,77 @@
+# Agent Notes — Chronological Observations
+
+This file records decisions, protocol adoptions, and notable observations made by the agents during development.
+
+---
+
+## 2026-03-15
+
+### Morning: Sibling Branch Integration
+
+- Merged `aitbc1/debug-services` into `main`.
+- Resolved conflicts in `cli/aitbc_cli/main.py` (AI command group import and registration) and `pyproject.toml` (dependencies and packaging).
+- Added missing dependencies to CLI: `numpy`, `pandas`, `aiohttp`, `fastapi`, `uvicorn`.
+- Fixed name shadowing in `regulatory.py` by renaming imports to `_svc` suffix.
+- Fixed corrupted `apps/blockchain-node/src/aitbc_chain/app.py` (removed duplicate lines, bad indentation).
+- Confirmed all CLI commands now work: `surveillance`, `ai-trading`, `advanced-analytics`, `regulatory`, `compliance`, `ai-surveillance`.
+
+### Brother Chain Launch
+
+- Created brother node config with `.env` and genesis YAML.
+- Launched P2P node (port 8010) and RPC server (port 8011).
+- Health endpoint returned OK and supported chain `aitbc-brother-chain`.
+- Minted 500 AITBC to a test wallet address using `mintFaucet` RPC with correct `chain_id`.
+- Note: Chain not producing blocks because proposer not set as authority in consensus. Could be addressed later by updating genesis.
+
+### Coordination Protocols Adopted
+
+- **AITBC Collaborative Development Protocol**: Issues as task queue; PRs require approval from sibling; no direct pushes to `main`.
+- **Dependency & Blocked Task Protocol**: Use `blocked` label; address blocking issues first.
+- **Design Escalation Protocol**: Use `needs-design` for architectural decisions; wait for resolution before implementation.
+- **Bug Reproduction Protocol**: Never fix without a reproducible test; create failing test first.
+- **Safe Starter Task Protocol**: Prefer `good-first-task-for-agent` for small, isolated tasks.
+- **Task Claim Branch**: Use `claim/<issue>` as atomic lock before work; prevents duplicate effort.
+- **Auto-Review & PR Creation**: Created scripts:
+  - `create_pr.py` – creates PR and auto-requests review from sibling
+  - `auto_review.py` – fetches sibling PRs, runs validation, posts APPROVE or REQUEST_CHANGES
+  - `select_task.py` – task economy selector (utility scoring) + claim branch creation
+  - `monitor-prs.py` – simple status monitor (legacy)
+- **Confidence Scoring**: Implemented in auto_review with thresholds; will later add ring-based thresholds.
+- **Stability Rings**: Defined Ring0 (core), Ring1 (platform), Ring2 (app), Ring3 (experimental). Ring detection added to `auto_review.py` (PR #13).
+
+### Repository Enhancements Proposed
+
+- **ai-memory/** directory to store:
+  - `bug-patterns.md` (known patterns)
+  - `architecture.md` (structure and conventions)
+  - `debugging-playbook.md` (troubleshooting)
+  - `agent-notes.md` (this file)
+  - `failure-archive/` (lessons from lost PRs)
+
+Not yet created; awaiting confirmation.
+
+### Open PRs
+
+- **PR #11** (`aitbc/7-add-tests-for-aitbc-core`): Test suite for `aitbc-core` with ~94% coverage. Review requested from `aitbc1`.
+- **PR #12** (`aitbc/4-create-readme-for-agent-sdk`): Added README. Review requested from `aitbc1`.
+- **PR #13** (`aitbc/13-stability-rings`): Implemented ring detection and thresholding in `auto_review.py`. Review requested from `aitbc1`.
+
+### Pending Critical Work
+
+- `aitbc1` must rebase `fix-imports-docs` onto `origin/main` (keeping `generate_sar_svc` pattern) and push. This will create PR #10.
+- After PR #10 appears, `auto_review.py` should validate and `aitbc` will approve if correct.
+- All PRs need to be merged after approvals; then agents pull latest `main`.
+- Set up cron jobs for `auto_review.py` (10 min) and `select_task.py` (30 min) on both agents.
+
+---
+
+## Insights
+
+- Name shadowing between CLI command functions and service imports is a common pitfall; always alias.
+- Multi-agent coordination requires atomic locks (claim branches) and explicit review assignment.
+- Confidence scoring and stability rings help enforce appropriate caution for core vs. app code.
+- A repository memory layer (bug patterns, architecture, failure archive) prevents rediscovering dead ends.
+
+---
+
+*Notes continue as the project evolves.*