AIPass/src/aipass/seedgo/README.md

<- Back to AIPass

Seedgo

Purpose: Standards compliance platform for AIPass. Audits all 11 core agents against 40 code standards + diagnostics, manages bypass rules, runs proof certification, and provides per-file checklist validation consumed by auto-fix hooks. Module: aipass.seedgo Version: 2.0.0 Created: 2026-03-05

---

Overview

What I Do

• Audit all 11 core agents against 40 code standards + diagnostics (architecture, CLI, imports, logging, naming, silent catch, deep nesting, etc.)
• Score files 0-100 per standard and report violations with actionable details
• Manage bypass rules (.seedgo/bypass.json) for deliberate exceptions
• Run pyright diagnostics across branches for type error detection
• Single-file checklist validation against all standards (consumed by PostToolUse auto-fix hook)
• Proof certification via proof/proof_query (triplet, plugin integrity, README currency)
• Custom function test coverage mapping via test_map
• README auto-generation and freshness checking

What I Don't Do

• Runtime monitoring (that's prax)
• Code execution or deployment

---

Commands

All commands available via drone @seedgo <command> or python3 -m aipass.seedgo <command>.

Via Drone (primary)

drone @seedgo                                          # Introspection (module list, version)
drone @seedgo --help                                   # Full command listing
drone @seedgo --version                                # Version string

# Audit
drone @seedgo audit aipass                             # Audit all 11 agents (40 standards + diagnostics)
drone @seedgo audit aipass @flow                       # Audit single branch
drone @seedgo audit inbox-ids                          # Inbox message-ID validation

# Standards Query
drone @seedgo standards_query aipass_standards         # List all 33 standards in pack
drone @seedgo standards_query aipass_standards cli     # Show specific standard content

# Per-file Check
drone @seedgo checklist <file>                         # Single-file standards check (hook consumer)
drone @seedgo checklist <directory>                    # Directory-wide check (globs *.py)

# Diagnostics
drone @seedgo diagnostics                              # Pyright type checking via audit pipeline

# Proof
drone @seedgo proof aipass                             # Proof certification (CERTIFIED / NOT CERTIFIED)
drone @seedgo proof_query aipass_proof triplet          # Query proof standard content

# Test Coverage
drone @seedgo test_map @seedgo                         # Function-level test coverage mapping

# README
drone @seedgo readme update @flow                      # README auto-generation for a branch

Via Python Module

python3 -m aipass.seedgo audit aipass                  # Same commands, direct execution
python3 -m aipass.seedgo standards_query aipass_standards cli

Note: proof, proof_query, and test_map commands work but are not listed in --help output (known TODO).

---

Architecture

seedgo/
├── apps/
│   ├── seedgo.py                    # Entry point — thin router (~290 lines)
│   │                                #   discover_modules() loads apps/modules/*.py
│   │                                #   route_command() dispatches to first handler returning True
│   ├── modules/                     # 10 business logic modules
│   │   ├── standards_audit.py       # Pack-aware compliance audit orchestrator
│   │   ├── standards_query.py       # Pack-aware content query
│   │   ├── diagnostics_audit.py     # Pyright diagnostics via audit pipeline
│   │   ├── checklist.py             # Per-file/dir standards check (hook consumer)
│   │   ├── seedgo_proof.py          # Proof certification orchestrator
│   │   ├── proof_query.py           # Proof content query
│   │   ├── inbox_audit.py           # Inbox message-ID validation
│   │   ├── permissions.py           # TRUSTED_CROSS_WRITERS list for hook + drone auth
│   │   ├── readme_update.py         # README generation module
│   │   └── test_map.py              # Custom function test coverage mapping
│   └── handlers/                    # 9 handler directories
│       ├── aipass_standards/        # 40 checker standards (120 files)
│       │   ├── *_check.py           # Checker implementations (score 0-100)
│       │   ├── *_content.py         # Queryable standard content
│       │   └── *.md                 # Standard documentation
│       ├── aipass_proof/            # 5 proof validators (11 files)
│       │   ├── triplet.py           # .trinity/ completeness
│       │   ├── interface.py         # AUDIT_SCOPE + function signatures
│       │   ├── plugin_integrity.py  # No hardcoded standard names
│       │   ├── content_naming.py    # Function naming conventions
│       │   └── readme_currency.py   # README freshness
│       ├── audit/                   # Audit implementation
│       │   ├── branch_audit.py      # Per-branch scoring engine
│       │   ├── discovery.py         # Branch discovery (CWD-first registry)
│       │   └── audit_display.py     # Rich result formatting
│       ├── bypass/                  # Bypass system
│       │   ├── bypass_handler.py    # .seedgo/bypass.json loader
│       │   └── ignore_handler.py    # .seedgo/ignore patterns
│       ├── config/                  # Configuration handlers
│       ├── diagnostics/             # Pyright integration + branch discovery
│       ├── json/                    # JSON tracking (json_handler)
│       ├── readme/                  # README generator + branch resolution
│       └── test_map/                # Function test coverage scanner
├── tests/                           # 38 test files, 1217 tests
├── drone_adapter.py                 # Drone routing bridge
├── .trinity/                        # Identity + memory
├── .seedgo/                         # Self-bypass rules
├── .ai_mail.local/                  # Mailbox
└── CLAUDE.md                        # Branch startup instructions

Key Patterns

Module auto-discovery: discover_modules() in seedgo.py loads all .py files from apps/modules/. Each module's handle_command(command, args) is called in discovery order; first returning True wins.

Pack discovery: Checker packs live in handlers/*_standards/ directories. standards_audit strips the _standards suffix for command routing (aipass_standards/ -> audit aipass). standards_query uses the full directory name (standards_query aipass_standards).

CWD-first registry: _find_registry() walks CWD parents first (for external project support), falls back to __file__ parents, uses *_REGISTRY.json glob (not hardcoded name).

Bypass system: .seedgo/bypass.json per branch. Each entry has file, standard, optional lines, and required reason. Checkers call is_bypassed() per violation. Bypass is intentional documented deviation, not ignoring.

---

The 40 Standards

Standard	Scope	What It Checks
architecture	entry_point	Module/handler separation, entry point structure
cli	all_files	Rich console usage, no bare print()
cli_flags	entry_point	--help, --version flag handling
commented_logger	all_files	No commented-out logger/logging calls
dead_code	branch_level	Unreachable functions and dead imports
debug_print	all_files	No debug print/pprint statements
deep_nesting	all_files	Max nesting depth 4 (AST-measured)
documentation	all_files	Docstrings on public functions
encapsulation	all_files	No cross-branch imports, proper isolation
error_handling	all_files	Try/except patterns, error propagation
handler_import	branch_level	apps/__init__.py contains from . import handlers
handlers	entry_point	Handler directory structure
hardcoded_key	all_files	No hardcoded API keys or secrets
hardcoded_path	all_files	No hardcoded absolute paths
help_text	all_files	--help content quality
imports	all_files	Import ordering and grouping
introspection	entry_point	No-args introspection gate
json_handler	branch_level	JSON handler test coverage validation
json_structure	all_files	json_handler import + log_operation calls
log_handler	all_files	Prax logger usage (not stdlib logging)
log_level	all_files	Correct log level usage
log_structure	all_files	Structured log message format
log_visibility	all_files	Log output in key operations
meta	all_files	File header metadata block
modules	all_files	Module structure and naming
naming	all_files	snake_case, column-0 constants
output_routing	all_files	Status output via @cli helpers, not raw console.print
permission_flags	all_files	No dangerous permission overrides
readme	branch_level	README.md exists and is current
ruff	branch_level + per-file	Ruff linter compliance
shebang	all_files	No shebang lines in library code
silent_catch	all_files	No bare except/pass patterns
stderr_routing	all_files	Proper stderr vs stdout usage
subcommand_help	entry_point	Subcommand --help interception before dispatch
template	branch_level	No unresolved spawn template markers
test_quality	branch_level	JSON handler test coverage (51 items, 11 categories)
todo	all_files	No unresolved TODO/FIXME/HACK comments
trigger	all_files	Trigger integration patterns
unused_function	branch_level	No unreferenced public functions
windows_compat	all_files	Cross-platform compatibility (no Unix-only APIs)

---

Hook Architecture

The hooks branch (src/aipass/hooks/) owns all hook infrastructure — engine, bridge, and 14 native handlers. Seedgo audits hooks via standards but does not own the hook system.

Provider settings route all events through the bridge (claude.py), which dispatches to native Python handlers:

Handler	Event	Category
prompt.global_loader	UserPromptSubmit	prompt
prompt.branch_loader	UserPromptSubmit	prompt
prompt.identity	UserPromptSubmit	prompt
notification.email	UserPromptSubmit	notification
security.edit_gate	PreToolUse	security
security.git_gate	PreToolUse	security
lifecycle.auto_fix	PostToolUse	lifecycle
lifecycle.auto_watchdog	PostToolUse	lifecycle
security.subagent_gate	SubagentStop	security
notification.stop_sound	Stop	notification
notification.announce	Notification	notification
notification.tool_sound	PreToolUse	notification
lifecycle.compact	PreCompact	lifecycle
lifecycle.rollover	PreCompact	lifecycle

---

Tests

• 38 test files, all passing
• 0 type errors (pyright)
• Key test areas: standards audit, checklist, bypass, JSON handler, hooks snapshot, permissions, proof, README, diagnostics, line coverage (plugin integrity, diagnostics, audit display, branch audit, architecture, checklist)

---

Integration Points

Depends On

• aipass.cli — Rich console, header formatting
• aipass.prax — Structured logging via logger
• aipass.drone — Branch resolution via normalize_branch_arg
• Python stdlib (pathlib, ast, importlib, json, re)

Provides To

• All branches — standards auditing via drone @seedgo audit aipass [@branch]
• All branches — content queries via drone @seedgo standards_query
• All branches — per-file checklist via hook (PostToolUse -> checklist)
• aipass.drone — in-process routing via drone_adapter.py

---

Known Issues / Tech Debt

• audit_display.py: 16 hardcoded display blocks for specific standards (DPLAN-0047 tracks dynamic refactor)
• proof, proof_query, test_map not listed in --help output
• documentation_check.py 5-line lookahead limitation for multi-line function signatures
• dead_code_check.py doesn't recognize iterdir() as valid discovery pattern
• Cross-branch file write detection recommended but not yet in standards (S73 finding)

---

Latest Audit (2026-07-11)

• Seedgo score: 100% (40/40 + diagnostics) — all standards green
• Tests: 1217 passed, 0 failed, 0 skipped
• Coverage: 208 public functions, 197 tested (95%)
• Type errors: 0

---

Last Updated: 2026-07-11

---

<- Back to AIPass