AIPass/src/aipass/devpulse/README.md

[← Back to AIPass](../../../README.md)

# DevPulse

**Purpose:** Orchestration hub for the AIPass ecosystem
**Module:** `aipass.devpulse`
**Status:** Active
**Last Updated:** 2026-04-10

---

## Overview

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.

### 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

```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 <path>       # Create new branch from template
drone @spawn update @branch      # Update branch scaffold
drone @spawn delete @branch      # Archive + deregister branch
```

---

## Integration Points

### 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

---

## 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)