aitbc/ai-memory/agent-notes.md

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.