S58: README rewrite + HERALD.md + fresh install fixes (#140)

* docs: rewrite README with verified claims + add HERALD.md progress tracker README rewritten and verified against live system: - All commands tested and confirmed working - drone systems shows 23 (15 core + 8 test), documented correctly - seedgo at 33 standards (was incorrectly stated as 34) - Docker setup-workspace.sh fork URL noted - setup.sh sudo requirement documented - prax monitor marked as interactive - Added Standards, Communication, and Structure sections - Removed session tracking (moved to HERALD.md) - Branch table expanded with roles and descriptions HERALD.md: Living progress doc for Patrick to read between sessions. Contains session history, active DPLANs, milestones, known issues. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * fix(install): registry format mismatch + seedgo CLI entry point Bugs found via fresh Docker install test: 1. setup.sh generated AIPASS_REGISTRY.json with branches as dict (keyed by name), but seedgo's discovery.py expected a list of dicts. Result: `drone @seedgo audit aipass` was completely broken on any fresh install. Fix: setup.sh now generates list format (matching existing registry). 2. setup.sh verified `seedgo --help` but seedgo has no CLI entry point — it's only accessible via `drone @seedgo`. Fix: check `drone @seedgo --help` instead, remove broken symlink attempt. 3. seedgo discovery.py now handles both list and dict registry formats defensively (in case old registries exist). 4. README updated to remove seedgo standalone CLI claims. Verified: full fresh install in Docker container — setup.sh completes successfully, drone systems shows 15 branches, seedgo audit runs clean. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-03-28 12:10:19 -07:00
parent 2e2a9dce10
commit 6f2333ec67
4 changed files with 193 additions and 53 deletions
@@ -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.*
@@ -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 <container>` 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 <container>` 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/<branch>/
-├── .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/
-│   ├── <branch>.py     # Entry point
-│   ├── modules/        # Business logic
-│   └── handlers/       # Implementation
+│   ├── <branch>.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

@@ -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 ==="
@@ -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)