diff --git a/HERALD.md b/HERALD.md new file mode 100644 index 00000000..813f45db --- /dev/null +++ b/HERALD.md @@ -0,0 +1,87 @@ +# AIPass Herald + +> The living record. What happened, what's changing, what matters. + +**Last updated:** 2026-03-28 | **Session:** 58 | **PRs merged:** 137 + +--- + +## Current State + +- **15 branches** operational +- **100% seedgo compliance** across all 15 branches, all 33 standards +- **2,000+ tests** system-wide +- **137 PRs** merged since inception + +## Recent Sessions + +### S58 — Night Shift: 100% Compliance (2026-03-28) +The big one. Every branch, every standard, 100%. Seven agents deployed overnight to fix the final 8 branches that were stuck at 99%. Commons was the hardest — test_quality at 68%, unused functions, architecture gaps, deep nesting. All fixed. Daemon needed plugin architecture bypasses. Memory and spawn needed test gaps filled. PR #137 (167 files, +12,843 lines). + +### S57 — Checker Consolidation + 14-Branch Sprint (2026-03-28) +Consolidated 3 overlapping test checkers into 2 clear ones: `testing` renamed to `error_handling`, `test_coverage` merged into `test_quality` v4.0 (51 items, 11 categories, 33 standards total). Dispatched all 14 non-devpulse branches simultaneously. Prax fixed the log_structure bug (double stack walk). Seedgo fixed the unused_function display bug (branch-level checkers now show details). PRs #132-135 merged. Multiple re-dispatches needed — branches need babysitting at scale. + +### S56 — Spawn Template Overhaul (2026-03-25) +Spawn delivered registry regeneration + update workflow (ported from Cortex). Registry grew from 26 to 41 files. All 12 applicable branches updated. 113 tests. PR #129 (168 files). 69 old remote branches deleted (74 down to 5). Persistent citizen branches now the standard. + +### S55 — Test Quality Standard (2026-03-25) +Expanded test quality framework: 48 items across 10 categories. Spawn template work: 23 READMEs, .gitignore exceptions, .spawn cleanup. Cortex investigation for working implementations. Git deny rules enforced on devpulse. .claude/settings.local.json unignored system-wide. PRs #127-128. + +### S54 — Test Template + Seedgo Checker (2026-03-25) +Built test_json_handler_template (43 tests). Dry run across 6 branches (227/228 passed). Dispatched seedgo to build the checker — v1 was file-existence (wrong), caught the flaw, rewrote to v2 (function coverage scanning). Custom test survey revealed two naming paradigms. Architecture clarified: default vs custom tests are separate standards. + +### S52 — Stale Scanner + Test Dispatch (2026-03-24) +Stale scanner upgraded (skip *_json dirs, full paths, code-only focus). System-wide test dispatch: 896 new tests across 6 branches. 3-agent seedgo audit found shallow test depth (32/34 checkers untested). Created DPLAN-0059 for test quality standard. + +### S51 — Compliance Wave (2026-03-24) +Full system audit: 96% avg, all 14 branches at 95%+. Three dispatch waves. PR #122 merged (75 files). CLI blocked by prax log_structure bug. Daemon split scheduler_cron from 920 to 388 lines. + +### S50 — First Night Shift (2026-03-24) +First autonomous night shift. PR #118 (75 files). Persistent git branches (citizen/{name} pattern). Drone module routing + output fix. @ enforcement complete. System avg ~96.6%. + +## Active DPLANs + +| DPLAN | Subject | Status | +|-------|---------|--------| +| 0031 | Drone audit + git workflow improvements | Open — master key concept, PR review gate | +| 0033 | Commons audit | Silent catch done, orphan cleanup remaining | +| 0034 | Backup audit | Silent catch done, scope/filtering remaining | +| 0035 | Spawn audit | Template overhaul complete, nesting deferred | +| 0036 | AI Mail audit | Silent catch done, nesting + reply-while-locked bug | +| 0049 | API compliance | 100% achieved | + +## Key Milestones + +| Date | Milestone | +|------|-----------| +| 2026-03-28 | 100% seedgo compliance — all 15 branches, all 33 standards | +| 2026-03-25 | Spawn template overhaul — registry regen, 41-file template | +| 2026-03-24 | First autonomous night shift — 6 branches dispatched, all returned | +| 2026-03-23 | System-wide silent catch wave — 14 branches, 93% avg | +| 2026-03-22 | Phase 1 diagnostic tools complete — 20 tools reviewed + accepted | +| 2026-03-20 | Branch audit DPLANs created — systematic quality improvement begins | +| 2026-03-18 | Persistent git branches — citizen/{name} pattern replaces throwaway feat/ | +| 2026-03-18 | Plan cleanup — 60+ plans closed, flow delivered --dry-run | + +## Known Issues + +- **ai_mail reply-while-locked bug**: `drone @ai_mail reply` gives "Unknown command" when target is locked instead of "branch is locked" +- **Memory bank venv missing**: vectorization fails for deleted emails, shows warning on every ai_mail archive +- **Ruff CI**: 474 lint violations in backlog +- **wake.py no --model flag**: dispatched branches use CLI default model +- **prax dashboard CLI routing**: argparse eats flags before module + +## System Numbers + +``` +Branches: 15 +Standards: 33 (was 34, consolidated in S57) +Tests: 2,000+ +PRs merged: 137 +Sessions: 58 +Compliance: 100% +``` + +--- + +*Updated by devpulse at session boundaries. Read this for the big picture, check STATUS.local.md in any branch for the details.* diff --git a/README.md b/README.md index 0e39ac28..cb2b8e7c 100644 --- a/README.md +++ b/README.md @@ -13,10 +13,15 @@ A multi-agent operating system where AI agents live as citizens in a shared file git clone https://github.com/AIOSAI/AIPass.git cd AIPass ./setup.sh -source .venv/bin/activate ``` -`setup.sh` creates a venv, installs the package, generates the branch registry (15 branches), bootstraps `.trinity/` identity files, copies an empty `.env` template to `~/.secrets/aipass/.env`, and installs Claude Code hooks. Idempotent — safe to re-run. +`setup.sh` creates a `.venv`, installs the package in editable mode, generates the branch registry (`AIPASS_REGISTRY.json`), bootstraps `.trinity/` identity files for all 15 branches, copies an `.env` template to `~/.secrets/aipass/.env`, installs Claude Code hooks, and creates a global symlink for `drone` (requires `sudo` — will prompt). Idempotent — safe to re-run. + +After setup, `drone` is available globally via `/usr/local/bin` symlink. No venv activation needed for CLI use. `seedgo` is accessed via `drone @seedgo`. For development (running tests, importing modules), activate the venv: + +```bash +source .venv/bin/activate +``` ### Manual (dev) @@ -33,10 +38,12 @@ pip install -e ".[dev]" # Editable install + dev tools nano ~/.secrets/aipass/.env ``` +Only needed if using the `api` branch (OpenRouter/OpenAI). Everything else works without API keys. + ### Verify ```bash -drone systems # Should show 15 branches +drone systems # Should list 15 core branches + 3 internal modules ``` ### Docker @@ -46,14 +53,16 @@ docker build -t aipass . docker run -d -p 8080:8080 aipass ``` -Opens a code-server IDE with Python, Node, and Claude Code pre-installed. Password is auto-generated — check `docker logs ` for the config path. +Opens a [code-server](https://github.com/coder/code-server) IDE with Python, Node.js, and Claude Code pre-installed. Auth is password-based — check `docker logs ` for the generated password. Inside the container: ```bash -bash setup-workspace.sh # Clones repo and installs +bash setup-workspace.sh # Clones repo into workspace and installs ``` +> **Note:** `setup-workspace.sh` clones from a fork by default. Edit the `FORK` variable in the script to point to your own fork, or change it to the upstream `AIOSAI/AIPass` URL. + ## Usage Start with devpulse — the orchestration hub: @@ -68,35 +77,41 @@ Talk to it. It dispatches to specialist branches and brings results back. You wo ### Core Commands ```bash -drone @branch --help # Any branch's commands -drone systems # List all branches -drone @ai_mail dispatch @memory "subject" "body" # Send inter-agent mail -drone @seedgo audit aipass # Run standards audit -drone @flow create . "task name" dplan # Create a plan -drone @git pr # Create PR via drone +drone @branch --help # Any branch's capabilities +drone systems # List all branches + modules +drone @ai_mail dispatch @memory "subject" "body" # Send inter-agent mail + wake target +drone @seedgo audit aipass # Run standards audit (all branches) +drone @seedgo audit aipass @branch # Audit a single branch +drone @flow create . "task name" dplan # Create a planning doc +drone @flow create . "task name" # Create an execution plan +drone @git pr "description" # Create PR via drone (atomic workflow) +drone @git status # Git status scoped to your branch +drone @prax monitor # Real-time log monitoring (interactive — Ctrl+C to exit) ``` Pattern: `drone @branch command [args]` — single-line, non-interactive. ### Branches -| Branch | What it does | -|--------|-------------| -| `devpulse` | Orchestration hub — start here | -| `drone` | CLI router — routes commands to branches | -| `seedgo` | Standards enforcement — 34 automated checks | -| `prax` | Logging and monitoring | -| `cli` | Terminal display and formatting | -| `flow` | Workflow management (FPLANs, DPLANs) | -| `ai_mail` | Inter-agent messaging and dispatch | -| `spawn` | Branch lifecycle and identity | -| `trigger` | Event-driven automation | -| `api` | LLM access via OpenRouter | -| `backup` | Backup system (snapshot, versioned, Drive) | -| `daemon` | Background scheduler | -| `memory` | Vector memory bank (ChromaDB) | -| `commons` | Social space for branches | -| `skills` | Capability framework | +15 citizen branches, each an autonomous agent with persistent memory: + +| Branch | Role | What it does | +|--------|------|-------------| +| `devpulse` | Manager | Orchestration hub — start here. Coordinates all other branches. | +| `drone` | Builder | CLI router — resolves `@name` to paths, routes commands to branches | +| `seedgo` | Builder | Standards enforcement — 33 automated checks, bypass system | +| `prax` | Builder | Logging infrastructure and real-time monitoring | +| `cli` | Builder | Terminal display, formatting, and output services | +| `flow` | Builder | Workflow management — FPLANs (execution) and DPLANs (planning) | +| `ai_mail` | Builder | Inter-agent messaging, dispatch, and wake system | +| `spawn` | Builder | Branch lifecycle — create, update, template management | +| `trigger` | Builder | Event-driven automation — 12 event types | +| `api` | Builder | LLM access via OpenRouter (requires API key) | +| `backup` | Builder | Multi-mode backup — snapshot, versioned, Google Drive | +| `daemon` | Builder | Background scheduler with plugin system | +| `memory` | Builder | Vector memory bank (ChromaDB) — search, archival | +| `commons` | Builder | Social space — posts, reactions, community features | +| `skills` | Builder | Capability framework for branch skills | ## How It Works @@ -106,41 +121,72 @@ Every branch has `.trinity/` files that persist across sessions: ``` .trinity/passport.json # Identity — role, purpose, principles -.trinity/local.json # Session history — tasks, learnings -.trinity/observations.json # Collaboration patterns over time +.trinity/local.json # Session history — tasks, learnings, key insights +.trinity/observations.json # Collaboration patterns observed over time ``` -New session starts, branch reads its memories, picks up where it left off. +New session starts, branch reads its memories, picks up where it left off. When local files reach capacity, they roll over into the `@memory` branch (ChromaDB vectors). Nothing is lost. + +### Standards + +Every branch is held to 33 automated standards checks via `seedgo`: + +```bash +drone @seedgo audit aipass # Full system audit +drone @seedgo audit aipass @api # Single branch +drone @seedgo checklist apps/module.py # Quick check on a file +``` + +Standards cover: architecture, CLI patterns, error handling, imports, logging, naming, test quality, documentation, and more. Branches can add justified bypasses in `.seedgo/bypass.json`. ### Structure ``` src/aipass// -├── .trinity/ # Identity & memory -├── .aipass/ # Branch prompt -├── .ai_mail.local/ # Mailbox +├── .trinity/ # Identity & memory (persists across sessions) +├── .aipass/ # Branch-specific system prompt +├── .ai_mail.local/ # Mailbox (inbox.json, sent/) +├── .seedgo/ # Standards bypass config +├── .claude/ # Claude Code settings (deny rules, permissions) ├── apps/ -│ ├── .py # Entry point -│ ├── modules/ # Business logic -│ └── handlers/ # Implementation +│ ├── .py # Entry point (handle_command, introspection) +│ ├── modules/ # Business logic / orchestration +│ └── handlers/ # Implementation details +├── tests/ # Branch test suite +├── logs/ # Prax log output └── README.md ``` -All branches follow this layout. `drone` resolves `@name` to paths via `AIPASS_REGISTRY.json`. +All branches follow this layout. `drone` resolves `@name` to filesystem paths via `AIPASS_REGISTRY.json`. + +### Communication + +Branches communicate via `ai_mail` — an internal messaging system: + +```bash +drone @ai_mail dispatch @target "Subject" "Body" # Send + wake target branch +drone @ai_mail email @target "Subject" "Body" # Send without waking (FYI only) +drone @ai_mail inbox # Check your inbox +``` + +Dispatch sends a message AND wakes the target branch (starts a Claude session in their directory). This is how devpulse coordinates work across the system. ### No Isolation -All 15 branches share the same filesystem and git repo. Each owns its directory and doesn't touch others. Dispatch locks prevent conflicts. Standards enforcement keeps things consistent. +All 15 branches share the same filesystem and git repo. Each owns its directory and doesn't touch others. A PR lockfile prevents concurrent git operations. Standards enforcement keeps things consistent. + +Git workflow is atomic via `drone @git pr` — one command handles: lock acquisition, branch creation, scoped staging, commit, push, PR creation, return to main, and lock release. ## Requirements - Python 3.10+ -- API keys optional (needed for `api` branch — OpenRouter/OpenAI) -- [Claude Code](https://docs.anthropic.com/en/docs/claude-code) recommended for hooks +- `sudo` access (for global CLI symlinks during setup) +- API keys optional (only needed for `api` branch — OpenRouter/OpenAI) +- [Claude Code](https://docs.anthropic.com/en/docs/claude-code) recommended (hooks provide branch identity, email notifications, auto-diagnostics) ## Status -Beta. 15 branches operational. 135+ PRs merged. 2,000+ tests. 100% compliance across 33 standards checks. +Beta. 15 branches. 137 PRs merged. 2,000+ tests. 100% compliance across 33 standards. See [HERALD.md](HERALD.md) for detailed progress and session history. ## License diff --git a/setup.sh b/setup.sh index 108f70b9..6063ad0b 100755 --- a/setup.sh +++ b/setup.sh @@ -61,8 +61,9 @@ else FAIL=1 fi -if seedgo --help &>/dev/null; then - echo " seedgo ... ok" +# seedgo is accessed via drone @seedgo, not as a standalone CLI +if drone @seedgo --help &>/dev/null; then + echo " seedgo ... ok (via drone @seedgo)" else echo " seedgo ... FAILED" FAIL=1 @@ -97,11 +98,11 @@ repo_root = sys.argv[1] src_dir = Path(repo_root) / "src" / "aipass" today = date.today().isoformat() -branches = {} +branches = [] # Discover modules under src/aipass/ for d in sorted(src_dir.iterdir()): if d.is_dir() and not d.name.startswith(("_", ".")): - branches[d.name] = { + branches.append({ "name": d.name, "path": str(d), "profile": "library", @@ -110,13 +111,13 @@ for d in sorted(src_dir.iterdir()): "status": "active", "created": today, "last_active": today, - } + }) # Add external branches: commons and skills for ext_name in ["commons", "skills"]: ext_path = Path(repo_root) / "src" / ext_name if ext_path.is_dir(): - branches[ext_name] = { + branches.append({ "name": ext_name, "path": str(ext_path), "profile": "library", @@ -125,7 +126,7 @@ for ext_name in ["commons", "skills"]: "status": "active", "created": today, "last_active": today, - } + }) registry = { "metadata": { @@ -349,7 +350,7 @@ echo "Creating global symlinks ..." VENV_BIN="$SCRIPT_DIR/.venv/bin" LOCAL_BIN="/usr/local/bin" -for cmd in drone seedgo; do +for cmd in drone; do if [ -f "$VENV_BIN/$cmd" ]; then if sudo ln -sf "$VENV_BIN/$cmd" "$LOCAL_BIN/$cmd" 2>/dev/null; then echo " $LOCAL_BIN/$cmd -> $VENV_BIN/$cmd" @@ -365,8 +366,9 @@ echo "" if [ "$FAIL" -eq 0 ]; then echo "=== Setup complete ===" echo "" - echo "drone and seedgo are available globally via /usr/local/bin symlinks." - echo "No venv activation needed." + echo "drone is available globally via /usr/local/bin symlink." + echo "seedgo is accessed via: drone @seedgo" + echo "No venv activation needed for CLI commands." echo "" else echo "=== Setup finished with errors ===" diff --git a/src/aipass/seedgo/apps/handlers/audit/discovery.py b/src/aipass/seedgo/apps/handlers/audit/discovery.py index 3a271ff4..125fd361 100644 --- a/src/aipass/seedgo/apps/handlers/audit/discovery.py +++ b/src/aipass/seedgo/apps/handlers/audit/discovery.py @@ -94,7 +94,12 @@ def discover_branches(include_private: bool = False) -> List[Dict[str, str]]: registry_dir = registry_path.parent - for branch in registry_data.get('branches', []): + raw_branches = registry_data.get('branches', []) + # Handle both list format and dict format (keyed by name) + if isinstance(raw_branches, dict): + raw_branches = list(raw_branches.values()) + + for branch in raw_branches: branch_name = branch.get('name', '') raw_path = branch.get('path', '') branch_path = Path(raw_path)