diff --git a/src/aipass/devpulse/README.md b/src/aipass/devpulse/README.md index 4ce8072c..bbb9e4f6 100644 --- a/src/aipass/devpulse/README.md +++ b/src/aipass/devpulse/README.md @@ -2,208 +2,34 @@ # DevPulse -**Purpose:** Orchestration hub for the AIPass ecosystem -**Module:** `aipass.devpulse` -**Status:** Active -**Last Updated:** 2026-04-10 +> Orchestration hub for AIPass. Plans, coordinates, dispatches. Never the builder. ---- +DevPulse is the central coordination branch. It does not ship features of its own — it works with the user on design, dispatches real work to branch specialists, tracks plans and memory, and keeps the system moving. If a task belongs to another branch, DevPulse emails that branch and waits for the reply. -## Overview +## Start here -DevPulse is the central coordination branch for AIPass. It plans, delegates, and tracks work across all 11 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. +| You want to | Read | +|---|---| +| Install, update, uninstall, or troubleshoot | [SETUP.md](SETUP.md) | +| What's happening right now | [STATUS.local.md](STATUS.local.md) | +| Identity, memory, session history | [`.trinity/`](.trinity/) | +| Diagnostic scanners | [`tools/`](tools/) | +| Branch health audits | [`branch_audits _only/`](branch_audits%20_only/) | +| Active plans | `drone @flow list open` | -### What DevPulse Does -- **Cross-branch orchestration** — Dispatch tasks to branches via AI Mail + wake -- **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 - ---- - -## Managed Directory — `src/aipass/` - -DevPulse orchestrates all branches under `src/aipass/`: - -``` -src/aipass/ -├── drone/ # Command routing — @ resolution, branch dispatch -├── seedgo/ # Standards & compliance — audits, checkers, packs -├── prax/ # Logging system — stack introspection, dual routing -├── cli/ # CLI framework — argument parsing, command registry -├── flow/ # Plan management — FPLANs, DPLANs, templates, tracking -├── ai_mail/ # Inter-branch comms — inbox, dispatch, wake -├── api/ # LLM access layer — OpenRouter, multi-provider, usage tracking -├── trigger/ # Event system — log watchers, event handlers -├── spawn/ # Branch lifecycle — create, update, delete, passport -├── memory/ # Memory bank — ChromaDB vectors, rollover, search -├── devpulse/ # Orchestration hub (you are here) -└── __init__.py -``` - -**11 registered branches:** drone, seedgo, prax, cli, flow, ai_mail, api, trigger, spawn, memory, devpulse - -## DevPulse Architecture - -``` -devpulse/ -├── .trinity/ # Identity + memory -│ ├── passport.json # Branch identity -│ ├── local.json # Session history + key learnings -│ └── observations.json # Collaboration patterns -├── .aipass/ # AI context -│ └── aipass_local_prompt.md -├── .spawn/ # Spawn metadata -├── apps/ # Entry point scaffold (minimal — devpulse.py + stubs) -├── tools/ # Diagnostic scanner suite (26 tools) -├── branch_audits _only/ # Living audit plans for all 11 branches + patrick -├── dropbox/ # Incoming files from other branches/users -├── docs/ # Tracked documentation -├── docs.local/ # Working files (gitignored) -├── DPLAN-*.md # Active design plans (8-10 at any time) -├── CLOSED_PLANS.local.json # Archive of completed plans -├── STATUS.local.md # Current work, issues, todos -└── README.md -``` - -DevPulse has a minimal `apps/` scaffold but is primarily a **manager** branch, not a builder. It coordinates via dispatch and sub-agents rather than implementing code. - ---- - -## Diagnostic Tools - -DevPulse maintains a suite of 26 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) | - -### Infrastructure -| Tool | What it checks | -|------|---------------| -| `log_scanner_v1.py` | Prax log files for errors/warnings | -| `key_exposure_scanner_v1.py` | API key exposure patterns in code | -| `meta_header_scanner_v1.py` | Module metadata headers compliance | -| `scanner_v1.py` | Base scanner framework | - -### Utilities -| Tool | What it does | -|------|-------------| -| `dev_central_to_devpulse.py` | Rename stale terms across files | -| `verify_branch.py` | Verify branch structure compliance | -| `git_lock_tool.py` | Manage git lock state for PRs | - -**Tool classification:** Hard checks (pass/fail) vs Advisory (flag for investigation). See DPLAN-0030 for full details. - ---- - -## Branch Audits - -DevPulse maintains living audit plans for every branch in `branch_audits _only/`. These are comprehensive health assessments created during adversarial audit sessions (S83 Wave 1-3) and continuously updated. - -Each audit tracks: -- **CRITICAL** — Must-fix issues (security, data loss, broken core features) -- **BUG** — Functional defects -- **STALE/DEAD** — Outdated references, dead code -- **QUALITY** — Performance, thread safety, architectural debt -- **DOCS** — Documentation gaps and inaccuracies - -| Branch | Audit File | Health | -|--------|-----------|--------| -| drone | DPLAN-0053 | YELLOW (23 BUG) | -| seedgo | DPLAN-0084 | GREEN | -| prax | DPLAN-0039 | GREEN | -| cli | DPLAN-0074 | YELLOW (2 CRITICAL) | -| flow | DPLAN-0082 | YELLOW (5 CRITICAL) | -| ai_mail | DPLAN-0036 | GREEN | -| api | DPLAN-0029 | YELLOW (3 CRITICAL) | -| trigger | DPLAN-0075 | YELLOW (1 CRITICAL) | -| spawn | DPLAN-0035 | YELLOW (12 BUG) | -| memory | DPLAN-0038 | GREEN | -| devpulse | DPLAN-0037 | RED | -| patrick | DPLAN-0086 | N/A | - ---- - -## Commands +## Invoke ```bash -# System status -drone systems # List all registered branches -drone @seedgo audit aipass # Run full standards audit - -# Flow plans -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 open # List active plans - -# Dispatch work -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 -drone @spawn update @branch # Update branch scaffold -drone @spawn delete @branch # Archive + deregister branch +cd src/aipass/devpulse +claude ``` ---- +Say "hi" and DevPulse picks up where the last session left off. -## Integration Points +## Role in one line -### Depends On -- `aipass.prax` — Logging (all logging goes through prax) -- `aipass.ai_mail` — Inter-branch communication + dispatch -- `aipass.flow` — Plan creation and tracking (DPLANs + FPLANs) -- `aipass.drone` — Command routing to all branches -- `aipass.spawn` — Branch lifecycle management -- `aipass.seedgo` — Standards verification + audit - -### Coordinates -- All 11 branches: drone, seedgo, prax, cli, flow, ai_mail, api, trigger, spawn, memory, devpulse +Manager, not builder. Coordinates via dispatch + sub-agents. Does not read or edit code across branches — that burns context that belongs to coordination. --- -## 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" — 26 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. - -The `branch_audits _only/` directory is DevPulse's health dashboard — living audit documents for every branch, updated during adversarial audit sessions and fix sweeps. Each audit tracks CRITICALs, BUGs, quality debt, and documentation gaps with current health ratings. - ---- [← Back to AIPass](../../../README.md) diff --git a/src/aipass/devpulse/SETUP.md b/src/aipass/devpulse/SETUP.md new file mode 100644 index 00000000..ba71c4a7 --- /dev/null +++ b/src/aipass/devpulse/SETUP.md @@ -0,0 +1,225 @@ +[← Back to DevPulse](README.md) + +# DevPulse Setup, Uninstall, Troubleshooting + +Everything you need to install, run, maintain, or remove DevPulse (and AIPass as a whole). Kept here so the DevPulse README can stay lean and loads quickly on every session startup. + +--- + +## Platform support at a glance + +| Platform | Install status | Notes | +|---|---|---| +| **Linux** (Ubuntu, Debian, Fedora, Arch) | Supported | Primary development target. `setup.sh` works out of the box. | +| **macOS** (Intel and Apple Silicon) | Supported | `setup.sh` works with minor caveats (see macOS section). | +| **Windows 10 / 11** | **In progress** | Native Windows support is actively being built. Track progress in [issue #261](https://github.com/AIOSAI/AIPass/issues/261). For now: use WSL2 (Ubuntu), or wait for the cross-platform `setup.py` landing in a PR soon. | + +--- + +## Linux install + +### Requirements + +- Python 3.10 or newer (`python3 --version`) +- `git`, `bash`, `sudo` +- Claude Code CLI installed and authenticated (`claude --version`) +- ~500 MB disk for the venv and dependencies + +### Install + +```bash +git clone https://github.com/AIOSAI/AIPass.git ~/Projects/AIPass +cd ~/Projects/AIPass +bash setup.sh +``` + +`setup.sh` will: +1. Create a Python venv at `.venv/` +2. Install AIPass in editable mode (`pip install -e .`) +3. Verify the `drone` and `aipass` CLI entry points +4. Create `~/.secrets/aipass/` with `chmod 700` and seed an `.env.example` +5. Generate the AIPass branch registry +6. Bootstrap branch identity files (`.trinity/passport.json` per branch) +7. Wire Claude Code hooks into `~/.claude/settings.json` +8. Create a global symlink at `/usr/local/bin/drone` (asks for `sudo`) + +### Post-install + +```bash +# Verify +drone systems + +# Enter the DevPulse branch +cd ~/Projects/AIPass/src/aipass/devpulse +claude +``` + +You should see DevPulse greet you, read its memory, and be ready. + +### Optional + +- Add API keys to `~/.secrets/aipass/.env` if you want LLM routing beyond Claude Code +- Set `AIPASS_HOME=~/Projects/AIPass` in your shell rc if you plan to use AIPass from other projects +- Add `export AIPASS_HOME=~/Projects/AIPass` to `~/.bashrc` **and** `~/.claude/settings.json` (the `env` section) — both are needed for full cross-project access + +--- + +## macOS install + +Same as Linux. `setup.sh` uses bash and runs on macOS out of the box. + +**Caveats**: +- `chmod 700` and `chown` work correctly on macOS's HFS+ and APFS +- `sudo ln -sf /usr/local/bin/drone` works but may prompt for your admin password +- Homebrew users: if you have multiple Python installs, make sure `python3` points to Python 3.10+ before running `setup.sh` + +--- + +## Windows install + +**Short version**: use [WSL2](https://learn.microsoft.com/en-us/windows/wsl/install) (Ubuntu) and follow the Linux instructions. Full native Windows support is landing in a PR soon — follow [issue #261](https://github.com/AIOSAI/AIPass/issues/261) for status. + +**Why it's in progress**: the current `setup.sh` uses bash, `sudo`, and `ln -sf /usr/local/bin/drone`, none of which translate to Windows. The `aipass init` command also writes a shell loop into `.claude/settings.json` that assumes Unix root `/`. Fixes are in flight: +- A cross-platform `setup.py` that replaces `setup.sh` on Windows +- A Python-based directory traversal replacing the bash loop in `aipass init` +- OS detection in `setup.sh` to skip the symlink step on Windows and print PATH instructions instead + +**Interim workaround**: install WSL2 with an Ubuntu distribution, then clone and run `setup.sh` inside WSL. Claude Code also runs well inside WSL. + +--- + +## Uninstall + +### Full removal (Linux / macOS) + +```bash +# 1. Remove the venv and repo +rm -rf ~/Projects/AIPass + +# 2. Remove the global drone symlink +sudo rm /usr/local/bin/drone + +# 3. Remove secrets (if you won't reinstall) +rm -rf ~/.secrets/aipass + +# 4. Clean Claude Code hooks +# Edit ~/.claude/settings.json and remove any "hooks" sections that reference AIPass paths. +# Safer: back up the file first. +cp ~/.claude/settings.json ~/.claude/settings.json.bak +nano ~/.claude/settings.json # or your editor of choice + +# 5. Clean your shell rc +# Remove any AIPASS_HOME export from ~/.bashrc, ~/.zshrc, etc. +``` + +### Partial removal (keeping secrets for reinstall) + +Skip step 3 above. Your `~/.secrets/aipass/.env` will persist and be reused on next install. + +### Windows (WSL2) + +Same as Linux, inside the WSL distribution. To also remove the WSL distribution itself: `wsl --unregister Ubuntu` from PowerShell. + +--- + +## Troubleshooting + +### `drone: command not found` + +Your venv is not activated or the `/usr/local/bin/drone` symlink is missing. + +```bash +# Option A: activate the venv +source ~/Projects/AIPass/.venv/bin/activate +drone systems + +# Option B: run via full path +~/Projects/AIPass/.venv/bin/drone systems + +# Option C: reinstall the symlink +sudo ln -sf ~/Projects/AIPass/.venv/bin/drone /usr/local/bin/drone +``` + +### `AIPASS_HOME not set` warnings + +```bash +# In your shell rc (~/.bashrc or ~/.zshrc) +export AIPASS_HOME=~/Projects/AIPass + +# Then restart the shell or: +source ~/.bashrc +``` + +Also add it to `~/.claude/settings.json` under the `env` block for Claude Code sessions to pick it up. + +### DevPulse greets you but doesn't read its memory + +Check that `.trinity/passport.json`, `.trinity/local.json`, and `.trinity/observations.json` exist in `src/aipass/devpulse/`. If they don't, run `bash setup.sh` again to re-bootstrap the identity files. + +### `drone @git system-pr` fails with a lock error + +```bash +drone @git lock # check the lock state +drone @git fix # attempt to fix broken git state +``` + +Do NOT use raw `git reset --hard` — merge conflicts are easier to resolve than lost work. + +### Branch mail not arriving + +```bash +drone @ai_mail inbox # check your inbox +drone @prax watch # watch the monitoring dashboard +``` + +A known issue at the end of S90 affected wake delivery; see the wake investigation in DPLAN-0125 Track E if you're running a recent build. + +### Tests fail on a fresh clone + +```bash +cd ~/Projects/AIPass +source .venv/bin/activate +python -m pytest src/aipass//tests/ +``` + +If tests fail because `AIPASS_HOME` leaks the real registry into test results, that's a known pattern — the tests need `monkeypatch.delenv("AIPASS_HOME")`. See S90 notes for the fixture pattern. + +### `.claude/settings.json` has `/home/patrick/` paths + +You pulled an old clone. The hardcoded paths were removed in commit `867dad0` (April 5, 2026). Pull the latest main and re-run `setup.sh`, which generates the settings dynamically from your local repo root. + +--- + +## Environment variables + +| Variable | Purpose | Set where | +|---|---|---| +| `AIPASS_HOME` | Lets external projects find the AIPass registry | `~/.bashrc` + `~/.claude/settings.json` env block | +| `AIPASS_CALLER_BRANCH` | Auto-set by dispatch; identifies the sending branch for feedback/mail | Runtime only, do not set manually | +| `AIPASS_CALLER_CWD` | Auto-set by dispatch; identifies the caller's project directory | Runtime only, do not set manually | + +Sensitive values (API keys, tokens, recovery codes) belong in `~/.secrets/aipass/.env`, not in shell rc or repo files. + +--- + +## Reporting bugs + +File issues at https://github.com/AIOSAI/AIPass/issues. + +Helpful info to include: +- OS and version +- Python version (`python3 --version`) +- Claude Code version (`claude --version`) +- The exact command you ran and the full error output +- Whether you cloned recently or have been on the same checkout for a while (clone age helps us distinguish current bugs from fixed-but-stale-clone issues) + +The first external bug report was [#261 by Gavin Rooney](https://github.com/AIOSAI/AIPass/issues/261) — that template is a good example of a useful report. + +--- + +## See also + +- [DevPulse README](README.md) — the lean entry point +- [AIPass root README](../../../README.md) — the whole framework +- [STATUS.local.md](STATUS.local.md) — current work and loose ends +- [issue #261](https://github.com/AIOSAI/AIPass/issues/261) — Windows compat tracking