4 Commits

Author SHA1 Message Date
clever-agent 8109091bc3 docs: update remaining references to renamed agents
- Fix automation-tracking.md to use new pool supervisor names
- Update session_state.md to reference implementation-pool-supervisor
- Fix pr-status-analyzer.md to reference pr-ci-test-fixer
2026-04-09 21:39:32 -04:00
HAL9000 a3762a4cc2 docs: add invariant-reconciliation module guide, extend automation tracking docs, update mkdocs nav
docs: add invariant-reconciliation module guide, extend automation tracking docs, update mkdocs nav

- Add docs/modules/invariant-reconciliation.md: module guide for InvariantReconciliationActor (v3.8.0)
- Extend docs/development/automation-tracking.md: all 16 supervisors, centralized tracking manager
- Update mkdocs.yml: add Modules nav section, Custom Sandbox Strategy to Development

ISSUES CLOSED: #5700

Co-authored-by: CleverThis <hal9000@cleverthis.com>
Co-committed-by: CleverThis <hal9000@cleverthis.com>
2026-04-09 09:22:43 +00:00
freemo 014033eed9 feat: enhance automation tracking with health monitoring and recovery
Add comprehensive automated health monitoring and recovery capabilities
to the automation tracking system for proactive agent management.

**Major Enhancements:**

1. **Standardized Interval Reporting**
   - Mandatory interval declaration in all tracking issues
   - Format: 'Reporting Interval: <interval> (Next report expected: <timestamp>)'
   - Enables precise staleness detection and recovery triggering

2. **Automated Health Monitoring (system-watchdog)**
   - New audit_automation_tracking_health() function runs every 5 minutes
   - Monitors all issues with 'Automation Tracking' label
   - Detects stalled agents when >20% overdue from expected interval
   - Calculates staleness ratios and time overdue metrics

3. **Automated Recovery System**
   - Kills stalled agent sessions via OpenCode Server API (port 4096)
   - Performs root cause analysis of session messages and agent definitions
   - Creates high-priority diagnostic issues with detailed findings
   - Automatically closes stale tracking issues with recovery notes
   - Provides human-readable remediation recommendations

**Agent Updates with Standardized Format:**

- **implementation-orchestrator**: Status updates (5 cycles) + health reports (10 cycles)
- **backlog-groomer**: Grooming reports (5 min) + health reports (50 min)
- **human-liaison**: Status updates (20 min monitoring cycles)
- **session-persister**: Event-driven checkpoints with standardized format
- **system-watchdog**: Enhanced with comprehensive recovery capabilities

**Template Standardization:**
- Unified header format across all tracking issues
- Health indicators and next actions sections
- Consistent metadata and automation signatures
- Support for active/warning/error status indicators

**Documentation Updates:**
- Comprehensive automated recovery process documentation
- Agent interval reference table with all timing details
- Recovery issue format and diagnostic workflow
- Health check algorithm and staleness threshold explanation

**Benefits:**
- Proactive detection of crashed or stuck agents (20% staleness threshold)
- Automated recovery reduces manual intervention requirements
- Root cause analysis provides actionable diagnostic information
- Standardized format improves searchability and monitoring
- Comprehensive health metrics enable system-wide visibility

This enhancement transforms the automation tracking system from passive
logging to active health monitoring with automated recovery capabilities.
2026-04-08 22:34:23 +00:00
freemo a323f07783 feat: implement new automation tracking system for agent supervision
Replace shared session state issue tracking with individual tracking issues
per agent to reduce noise and improve searchability.

**Agent Updates:**
- session-persister: [AUTO-SESSION] prefix with cycle management
- implementation-orchestrator: [AUTO-IMP-POOL] prefix for health reports
- system-watchdog: [AUTO-WATCHDOG] prefix for system health
- backlog-groomer: [AUTO-GROOMER] prefix + backup cleanup functionality
- human-liaison: [AUTO-LIAISON] prefix for status updates

**New Features:**
- Standardized issue title format: [AUTO-<PREFIX>] <TYPE> (Cycle <N>)
- Announcement format: [AUTO-<PREFIX>] Announce: <message>
- Automatic cleanup to prevent issue accumulation
- Required 'Automation Tracking' label for filtering
- Validation script for format compliance

**Documentation:**
- Complete system documentation at docs/development/automation-tracking.md
- Added to mkdocs.yml navigation
- Validation script at scripts/validate_automation_tracking.py

**Benefits:**
- Reduced noise from shared tracking issue
- Better searchability with agent-specific prefixes
- Cleaner history per agent type
- Easier debugging with focused issue threads
- Automatic cleanup prevents accumulation

Closes automation tracking system implementation requirements.
2026-04-08 21:28:46 +00:00