From 6a703ffba371d5890bf2def4ad88c598b3ff7aa0 Mon Sep 17 00:00:00 2001 From: AIOSAI Date: Sun, 22 Mar 2026 02:34:05 -0700 Subject: [PATCH] feat(devpulse): update READMEs with diagnostic tooling, current status MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Root README: session count 38→44, PRs 95→106+, tests 733→744, diagnostic tooling section (20 scanners), seedgo integration research, refreshed current priorities. DevPulse README: full rewrite — added tools/ directory with all 20 scanner descriptions organized by category, updated branch count to 15, current architecture tree, dispatch commands. Also includes: commons db.py fix, commons gitignore update, commons local prompt update, test_merge_ask.txt cleanup. Co-Authored-By: Claude Opus 4.6 (1M context) --- README.md | 38 ++++++--- src/aipass/devpulse/README.md | 98 +++++++++++++++++----- src/aipass/devpulse/test_merge_ask.txt | 0 src/commons/.aipass/aipass_local_prompt.md | 2 +- src/commons/.gitignore | 1 + src/commons/apps/handlers/database/db.py | 28 +++---- 6 files changed, 117 insertions(+), 50 deletions(-) delete mode 100644 src/aipass/devpulse/test_merge_ask.txt diff --git a/README.md b/README.md index 25e40510..5c926963 100644 --- a/README.md +++ b/README.md @@ -16,31 +16,32 @@ An operating system for AI agents. Not a chatbot wrapper. Not a prompt chain. A - **15 citizens** work in the same filesystem without isolation (no git worktrees, no sandboxes) - **Dispatch locks** prevent conflicts — if an agent is working, incoming tasks queue instead of spawning duplicates - **Persistent memory** survives across sessions via `.trinity/` files (identity, session history, collaboration patterns) -- **Standards enforcement** keeps the system consistent as it grows (seedgo runs 24+ automated checks) +- **Standards enforcement** keeps the system consistent as it grows (seedgo runs 24 automated checks) +- **Diagnostic tooling** — 20 standalone scanners cover code quality, security, documentation, and compliance - **Inter-agent messaging** lets citizens email each other, dispatch tasks, and wake each other up - **Everything is tracked** — design plans (DPLANs), execution plans (FPLANs), and seedgo audits make changes traceable even when 500+ files change in a single session - **Init anywhere** — `aipass init` turns any directory into a self-contained AI workspace with its own registry, identity, and memories. No repo required. A business project, a research folder, a side project — each gets its own isolated environment that works immediately ## Current State: Beta -**It works.** All 15 branches operational. 95+ PRs merged. 38 orchestration sessions. 733 tests across the system. 173 drone commands discovered. The system is past prototyping — we're in the hardening phase, building diagnostic tooling and iterating branch by branch. +**It works.** All 15 branches operational. 106+ PRs merged. 44 orchestration sessions. 744 tests across the system. 173 drone commands discovered. The system is past prototyping — we're in the hardening phase, with diagnostic tooling complete and seedgo integration next. **Recently completed:** +- **Diagnostic tooling suite** — 20 standalone scanners built, validated against API ground truth, and personally reviewed. Covers: silent catches, dead code, unused functions, deep nesting, debug prints, commented loggers, hardcoded keys, URL injection, magic numbers, TODO tracking, help text, README freshness, stale terminology, command verification, test coverage, prompt quality, and more. All follow `{concern}_scanner_v1.py` convention with `@branch` / `--all` / `--summary` flags. +- **Seedgo integration research** — 15-agent analysis mapped how all 20 scanners integrate into seedgo's auto-discovery checker system. 10 tools map to hard checks, 7 are advisory (investigation tools). Integration plan ready for dispatch. +- **3-tier logging revision** — handlers can now use `logger.info/warning` (previously prohibited). 112 commented-out logger calls across API handlers alone. DPLAN-0040 created for seedgo standard update. +- **Branch audit cycle** — DPLANs created per branch (API, commons, ai_mail, spawn, backup, prax, memory, drone). 4 branches dispatched and verified (commons DB path fixed, ai_mail purge consolidated, spawn templates updated, backup archived 8 files). - **Dispatch UX redesign** — `drone @ai_mail dispatch @target "Subject" "Body"` sends + wakes in one command. `--fresh` flag for clean sessions. `email` command for mail-only (no wake). Fully tested. - **PR v2 workflow** — commit-on-main architecture. Changes never leave your working tree. Feature branches are just pointers for GitHub's PR system. No more disappearing files. -- **Handler guard fix** — cross-branch handler imports blocked by `.py` files from other branches. Command-line `python3 -c` allowed through. 13 branches updated. -- **Memory vectorization fix** — batch processing (2 subprocess calls instead of 228), decoupled from startup trigger, explicit `drone @memory process-plans` command. 113 plan files vectorized in ~1 minute. -- **Diagnostic tooling** — 4 scanners built: dead code (14 unused files found), command inventory (173 commands), prompt quality (6 rich/4 basic/5 stub), test coverage (733 tests, 26% module coverage). -- **Prax monitor** — fully operational with inotify file watching, branch detection, polling fallback with actionable error messages. -- **Plan cleanup** — 60+ FPLANs/DPLANs closed. Templates updated with "close immediately when done" rule. -- **System governance** — git workflow, commit signing, DPLAN/FPLAN documentation, logging/debugging guidelines, `.archive/` pattern all codified in the global prompt. +- **Prax monitor** — fully operational with inotify file watching, branch detection, full message display. Used as secondary terminal to work around Claude Code's scroll limitation. **What we're solving now:** -- **Branch-by-branch audit** — walking through every branch from devpulse, testing commands, noting issues, dispatching fixes. API branch audit in progress (DPLAN-0029). -- **Local prompt enrichment** — 5 branches still on 14-line stubs (ai_mail, backup, cli, drone, prax). Rich prompts = less babysitting. -- **Test coverage expansion** — 9 branches have zero tests. Building toward comprehensive coverage using the test scanner for visibility. +- **Seedgo checker integration** — porting diagnostic tool logic into seedgo's `*_check.py` auto-discovery pattern. Goal: `drone @seedgo audit aipass` runs 34+ checks (24 existing + 10 new from diagnostic tools). +- **Branch-by-branch audit** — walking through every branch from devpulse, testing commands, noting issues, dispatching fixes. API branch audit complete (DPLAN-0029), 6 more branch DPLANs in progress. +- **Local prompt enrichment** — template finalized (DPLAN-0032), ready for rollout to 5 stub branches. +- **Test coverage expansion** — 9 branches have zero tests. 744 tests total, 27% module coverage. Test scanner provides per-branch visibility. - **Cross-platform reliability** — Linux and Windows tested. macOS structurally supported. All paths use `pathlib`, secrets at `~/.secrets/aipass/`. - **Agent agnosticism** — currently focused on [Claude Code](https://docs.anthropic.com/en/docs/claude-code) (hooks for auto-diagnostics, prompt injection, session recovery). But AIPass is designed to not depend on any single provider. `agents.md` and `gemini.md` can bootstrap the system for Codex and Gemini — you lose hooks but keep the core. @@ -90,9 +91,9 @@ Every branch is a citizen — an expert in its domain with its own memories and | Branch | Role | |--------|------| -| `devpulse` | **Start here.** Orchestration hub — coordinates everything | +| `devpulse` | **Start here.** Orchestration hub — coordinates everything, maintains 20 diagnostic tools | | `drone` | AI-friendly CLI — every command is a single-line, non-interactive call | -| `seedgo` | Standards enforcement — 21-standard audit pack, system compliance | +| `seedgo` | Standards enforcement — 24-standard audit pack, system compliance | | `prax` | Logging and monitoring (the only logger in the system) | | `cli` | Terminal display, stderr routing, project commands | | `flow` | Workflow management — FPLANs (execution) and DPLANs (design) | @@ -138,6 +139,17 @@ Every citizen has `.trinity/` files: These grow over time. A citizen that's been through 20+ sessions knows things — patterns, gotchas, preferences, past decisions. When context compacts (conversation gets too long), memories survive because they're written to disk. When a new session starts, the citizen reads its memories and picks up where it left off. +### Diagnostic Tooling + +DevPulse maintains 20 standalone scanners in its `tools/` directory — purpose-built for AI consumption. Each scanner follows the same CLI pattern (`@branch`, `--all`, `--summary`) and targets a single concern: + +- **Code quality** — silent catches, dead code, unused functions, deep nesting, raw prints, commented loggers +- **Security** — hardcoded keys, partial key display, URL injection +- **Documentation** — stale help text, README freshness, prompt quality, TODO tracking +- **Consistency** — magic numbers, stale terminology, command verification, test coverage + +Tools surface patterns. Patterns create conversations. Conversations improve the system. Run a scanner, get instant visibility into code quality across all 15 branches without reading a single file. + ## Architecture ``` diff --git a/src/aipass/devpulse/README.md b/src/aipass/devpulse/README.md index be6a7568..1da661cf 100644 --- a/src/aipass/devpulse/README.md +++ b/src/aipass/devpulse/README.md @@ -3,17 +3,19 @@ **Purpose:** Orchestration hub for the AIPass ecosystem **Module:** `aipass.devpulse` **Status:** Active +**Last Updated:** 2026-03-22 --- ## Overview -DevPulse is the central coordination branch for AIPass. It plans, delegates, and tracks work across all 10 branches in the ecosystem. Think of it as the project manager — it doesn't build modules itself, but dispatches work to branch agents, monitors results, and maintains system-wide visibility. +DevPulse is the central coordination branch for AIPass. It plans, delegates, and tracks work across all 15 branches in the ecosystem. Think of it as the project manager — it doesn't build modules itself, but dispatches work to branch agents, monitors results, and maintains system-wide visibility. ### What DevPulse Does - **Cross-branch orchestration** — Dispatch tasks to branches via AI Mail + wake -- **System-wide planning** — Create and manage flow plans (FPLANs) for multi-phase work -- **Status tracking** — Dashboard, dev notes, session history +- **System-wide planning** — Create and manage DPLANs (design) and FPLANs (execution) +- **Diagnostic tooling** — 20 standalone scanners for code quality, security, and compliance +- **Status tracking** — Session history, branch audits, system health - **Architecture discussions** — Work with the user on design decisions - **Agent coordination** — Deploy sub-agents in parallel for research and builds @@ -29,19 +31,22 @@ src/aipass/ ├── seedgo/ # Standards & compliance — audits, checkers, packs ├── prax/ # Logging system — stack introspection, dual routing ├── cli/ # CLI framework — argument parsing, command registry -├── flow/ # Plan management — FPLANs, templates, tracking +├── flow/ # Plan management — FPLANs, DPLANs, templates, tracking ├── ai_mail/ # Inter-branch comms — inbox, dispatch, wake -├── api/ # API layer — external interfaces +├── api/ # API layer — OpenRouter, Google, usage tracking ├── trigger/ # Event system — log watchers, event handlers ├── spawn/ # Branch lifecycle — create, update, delete, passport ├── devpulse/ # Orchestration hub (you are here) ├── daemon/ # Background scheduler — cron, plugins, monitoring -├── backup/ # Backup utilities -├── memory/ # Memory bank (planned) +├── backup/ # Backup & archival utilities +├── memory/ # Memory bank — ChromaDB vectors, rollover, search └── __init__.py + +src/commons/ # Shared utilities — config, database, helpers +src/skills/ # Skill system — discovery, registry, lifecycle ``` -**10 registered branches:** drone, seedgo, prax, cli, flow, ai_mail, api, trigger, spawn, devpulse +**15 registered branches:** drone, seedgo, prax, cli, flow, ai_mail, api, trigger, spawn, devpulse, daemon, backup, memory, commons, skills ## DevPulse Architecture @@ -49,13 +54,16 @@ src/aipass/ devpulse/ ├── .trinity/ # Identity + memory │ ├── passport.json # Branch identity -│ ├── local.json # Session history + active tasks +│ ├── local.json # Session history + key learnings │ └── observations.json # Collaboration patterns ├── .aipass/ # AI context -│ └── branch_system_prompt.md +│ └── aipass_local_prompt.md ├── .spawn/ # Spawn metadata -├── docs/ +├── tools/ # Diagnostic scanner suite (20 tools) +├── docs/ # Tracked documentation +├── docs.local/ # Working files (gitignored) ├── tests/ +├── STATUS.local.md # Current work, issues, todos └── README.md ``` @@ -63,24 +71,70 @@ DevPulse has no `apps/` directory — it's a **manager** branch, not a builder. --- +## Diagnostic Tools + +DevPulse maintains a suite of 20 standalone diagnostic scanners in `tools/`. Each follows the `{concern}_scanner_v1.py` naming convention and supports `@branch`, `--all`, and `--summary` flags. + +### Code Quality +| Tool | What it checks | +|------|---------------| +| `silent_catch_scanner_v1.py` | Except blocks with no logging or raise | +| `silent_catch_scanner_v2.py` | Same + tier-aware grouping (entry/module/handler) | +| `commented_logger_scanner_v1.py` | Commented-out `# logger.*()` calls | +| `debug_print_scanner_v1.py` | Raw `print()` that should use Rich console | +| `deep_nesting_scanner_v1.py` | Functions with nesting depth > 3 | +| `long_function_scanner_v1.py` | Top N longest functions (informational) | +| `unused_function_scanner_v1.py` | Functions defined but never called | +| `dead_code_scanner_v1.py` | Module/handler files with zero references | +| `todo_scanner_v1.py` | TODO/FIXME/HACK/XXX comments | +| `fallback_scanner_v1.py` | Intentional silent fallback patterns | + +### Security +| Tool | What it checks | +|------|---------------| +| `hardcoded_key_scanner_v1.py` | API key patterns in source (0 findings = good) | +| `partial_key_scanner_v1.py` | `key[:N]` partial display patterns | +| `url_injection_scanner_v1.py` | Unencoded URL params in f-strings | + +### Documentation & Consistency +| Tool | What it checks | +|------|---------------| +| `help_text_scanner_v1.py` | `python3` refs that should be `drone @branch` | +| `readme_freshness_scanner_v1.py` | README date vs newest code file | +| `prompt_scanner_v1.py` | Local prompt quality (RICH/BASIC/STUB/MISSING) | +| `test_scanner_v1.py` | Pytest coverage per branch + module | +| `command_scanner_v1.py` | Verifies drone commands are routable | +| `magic_number_scanner_v1.py` | Hardcoded numbers (cross-file consistency) | +| `stale_scanner_v1.py` | Outdated terminology (17 tracked keywords) | + +### Utilities +| Tool | What it does | +|------|-------------| +| `dev_central_to_devpulse.py` | Rename stale terms across files | +| `verify_branch.py` | Verify branch structure compliance | + +**Tool classification:** Hard checks (pass/fail) vs Advisory (flag for investigation). See DPLAN-0030 for full details. + +--- + ## Commands ```bash # System status drone systems # List all registered branches -drone @seedgo verify # Verify standards packs drone @seedgo audit aipass # Run full standards audit # Flow plans -drone @flow create . "Subject" # Create plan (default template) +drone @flow create . "Subject" # Create FPLAN (execution plan) +drone @flow create . "Subject" dplan # Create DPLAN (design/planning) drone @flow create . "Subject" master # Create master plan (multi-phase) -drone @flow list # List active plans -drone @flow close FPLAN-XXXX # Close a plan +drone @flow list open # List active plans # Dispatch work -drone @ai_mail send @target "Subject" "Body" --dispatch -drone @ai_mail dispatch wake @target # Wake branch agent -drone @ai_mail dispatch wake --fresh @target # Fresh session +drone @ai_mail dispatch @target "Subject" "Body" # Send + wake (one command) +drone @ai_mail email @target "Subject" "Body" # Just mail, no wake +drone @ai_mail dispatch wake @target # Wake only +drone @ai_mail dispatch wake --fresh @target # Fresh session wake # Branch management drone @spawn create # Create new branch from template @@ -95,16 +149,18 @@ drone @spawn delete @branch # Archive + deregister branch ### Depends On - `aipass.prax` — Logging (all logging goes through prax) - `aipass.ai_mail` — Inter-branch communication + dispatch -- `aipass.flow` — Plan creation and tracking +- `aipass.flow` — Plan creation and tracking (DPLANs + FPLANs) - `aipass.drone` — Command routing to all branches - `aipass.spawn` — Branch lifecycle management -- `aipass.seedgo` — Standards verification +- `aipass.seedgo` — Standards verification + audit ### Coordinates -- All 10 branches: drone, seedgo, prax, cli, flow, ai_mail, api, trigger, spawn, devpulse +- All 15 branches: drone, seedgo, prax, cli, flow, ai_mail, api, trigger, spawn, devpulse, daemon, backup, memory, commons, skills --- ## Role DevPulse is a **manager** branch, not a builder. It delegates code tasks to sub-agents and branch agents. Its context window is reserved for coordination, planning, and architecture — not for reading and editing files across the codebase. + +The `tools/` directory is DevPulse's "tool shed" — standalone diagnostic scripts for investigating code quality across all branches. These tools surface patterns and create conversations. They're built for AI consumption: run a scanner, get instant visibility, decide what matters. diff --git a/src/aipass/devpulse/test_merge_ask.txt b/src/aipass/devpulse/test_merge_ask.txt deleted file mode 100644 index e69de29b..00000000 diff --git a/src/commons/.aipass/aipass_local_prompt.md b/src/commons/.aipass/aipass_local_prompt.md index 952e31cb..192da41d 100644 --- a/src/commons/.aipass/aipass_local_prompt.md +++ b/src/commons/.aipass/aipass_local_prompt.md @@ -37,7 +37,7 @@ drone @commons --help # Full command list - Commons lives at `src/commons/` (outside `src/aipass/`), so path resolution differs from other branches - Branch identity detected via `AIPASS_CALLER_CWD` env var (set by drone) + `.trinity/passport.json` walk-up -- DB at `~/.aipass/commons.db` (or `$AIPASS_ROOT/.aipass/commons.db`) +- DB at `src/commons/commons.db` (resolved by walking up from `__file__` to `.trinity/`) - Registry lookup uses `AIPASS_REGISTRY.json`, found by walking up from package location ## Integration diff --git a/src/commons/.gitignore b/src/commons/.gitignore index 9cf1dfc4..b09f4b69 100644 --- a/src/commons/.gitignore +++ b/src/commons/.gitignore @@ -12,3 +12,4 @@ build/ *.log *.tmp *.swp +*.db diff --git a/src/commons/apps/handlers/database/db.py b/src/commons/apps/handlers/database/db.py index ef9443f9..cd4ba7b4 100644 --- a/src/commons/apps/handlers/database/db.py +++ b/src/commons/apps/handlers/database/db.py @@ -14,8 +14,8 @@ and schema bootstrapping for The Commons social network. Pure sqlite3 stdlib - no external dependencies. -Database location: {project_root}/.aipass/commons.db -resolved by walking up from __file__ to find project root. +Database location: {branch_root}/commons.db +resolved by walking up from __file__ to find the branch root (src/commons/). """ import os @@ -32,20 +32,18 @@ from commons.apps.handlers.json import json_handler # DATABASE PATHS # ============================================================================= -def _find_project_root() -> Optional[Path]: +def _find_branch_root() -> Optional[Path]: """ - Walk up from this file to find the project root. + Walk up from this file to find the commons branch root. - Looks for AIPASS_REGISTRY.json as the project root marker. - This file only exists at the true project root, unlike .aipass/ - which exists at both branch and project levels. + Looks for .trinity/ directory as the branch root marker. Returns: - Path to project root, or None if not found. + Path to branch root (src/commons/), or None if not found. """ current = Path(__file__).resolve().parent for _ in range(10): - if (current / "AIPASS_REGISTRY.json").exists(): + if (current / ".trinity").is_dir(): return current parent = current.parent if parent == current: @@ -59,20 +57,20 @@ def _get_db_path() -> Path: Resolve the database file path. Resolution order: - 1. Walk up from __file__ to find project root → {root}/.aipass/commons.db - 2. AIPASS_ROOT environment variable → {AIPASS_ROOT}/.aipass/commons.db + 1. Walk up from __file__ to find branch root → {branch_root}/commons.db + 2. AIPASS_ROOT environment variable → {AIPASS_ROOT}/src/commons/commons.db 3. Fallback → ~/.aipass/commons.db Returns: Path to the commons.db file. """ - project_root = _find_project_root() - if project_root: - return project_root / ".aipass" / "commons.db" + branch_root = _find_branch_root() + if branch_root: + return branch_root / "commons.db" aipass_root = os.environ.get("AIPASS_ROOT", "") if aipass_root: - return Path(aipass_root) / ".aipass" / "commons.db" + return Path(aipass_root) / "src" / "commons" / "commons.db" return Path.home() / ".aipass" / "commons.db"