From 325a876c875e1f3e9298e8f3ec78b145d9734bc4 Mon Sep 17 00:00:00 2001 From: HAL 9000 Date: Thu, 9 Apr 2026 08:47:33 +0000 Subject: [PATCH 1/2] docs(automation-tracking): document required labels for tracking issues All automation tracking issues must now include Type/Automation, State/In Progress, and Priority/Medium in addition to the existing Automation Tracking label requirement. Also adds docs-writer agent to the agent prefix table and reporting intervals table. --- docs/development/automation-tracking.md | 71 ++++++++++++++++++------- 1 file changed, 53 insertions(+), 18 deletions(-) diff --git a/docs/development/automation-tracking.md b/docs/development/automation-tracking.md index 6711acc9f..706db391f 100644 --- a/docs/development/automation-tracking.md +++ b/docs/development/automation-tracking.md @@ -44,12 +44,34 @@ For emergency announcements or important messages: | system-watchdog | `AUTO-WATCHDOG` | `[AUTO-WATCHDOG] System Health (Cycle 8)` | | backlog-groomer | `AUTO-GROOMER` | `[AUTO-GROOMER] Grooming Report (Cycle 23)` | | human-liaison | `AUTO-LIAISON` | `[AUTO-LIAISON] Status Update (Cycle 67)` | +| docs-writer | `AUTO-DOCS` | `[AUTO-DOCS] Documentation Report (Cycle 1)` | ## Required Labels -All automation tracking issues MUST include: -- **`Automation Tracking`** - Primary label for filtering -- Additional agent-specific labels as appropriate +All automation tracking issues MUST include **all four** of the following labels: + +| Label | Purpose | +|-------|---------| +| **`Automation Tracking`** | Primary label for filtering all automation issues | +| **`Type/Automation`** | Classifies the issue as automation-related | +| **`State/In Progress`** | Marks the issue as actively being worked on | +| **`Priority/Medium`** | Sets the default priority for tracking issues | + +> **Note:** These labels are org-level labels. Use their numeric IDs when applying via the API: +> - `Automation Tracking` → ID 1398 +> - `Type/Automation` → ID 1397 +> - `State/In Progress` → ID 843 +> - `Priority/Medium` → ID 860 + +### Applying Labels via API + +```bash +# Apply all required labels to a tracking issue +curl -s -X PUT "https://git.cleverthis.com/api/v1/repos///issues//labels" \ + -H "Authorization: token $FORGEJO_PAT" \ + -H "Content-Type: application/json" \ + -d '{"labels": [1398, 1397, 843, 860]}' +``` ## Interval Reporting and Health Monitoring @@ -74,6 +96,7 @@ This enables automated health monitoring by the system-watchdog to detect stalle | human-liaison | Status Update | Every 20 minutes (10 cycles) | Human activity monitoring | | system-watchdog | Health Report | Every 30 minutes (6 cycles) | System-wide health check | | session-persister | Checkpoint | Event-driven (variable) | After significant state changes | +| docs-writer | Documentation Report | Every 10 cycles (~3.3 hours) | Documentation update status | ### Automated Health Monitoring @@ -84,7 +107,7 @@ The **system-watchdog** automatically monitors all automation tracking issues: 3. **Detects stalled agents** when tracking issue is >20% overdue from expected interval 4. **Triggers automated recovery actions**: - Kills stalled agent sessions via OpenCode Server API (port 4096) - - Performs root cause analysis by examining session messages and agent definitions + - Performs root cause analysis by examining session messages and agent definitions - Creates high-priority diagnostic issues with findings and remediation suggestions - Closes stale tracking issues with recovery notes - Posts alerts for manual intervention where needed @@ -96,7 +119,7 @@ When a stalled agent is detected: 1. **Session Termination**: All matching agent sessions are gracefully terminated 2. **Root Cause Analysis**: Automated analysis examines: - Recent session messages and tool call history - - Related Forgejo issues and PR status + - Related Forgejo issues and PR status - Agent definition and configuration - System resource availability 3. **Diagnostic Issue Creation**: Creates issue with format `[AUTO-RECOVERY] Agent Failure Analysis` @@ -110,7 +133,7 @@ When a stalled agent is detected: **Agent Prefix**: **Detection Time**: -**Stale Issue**: # +**Stale Issue**: # **Time Overdue**: minutes **Staleness Ratio**: x expected interval @@ -119,9 +142,9 @@ When a stalled agent is detected: ## Recovery Actions Taken 1. ✅ Session Termination: Killed stalled sessions -2. ✅ Tracking Cleanup: Closed stale tracking issue +2. ✅ Tracking Cleanup: Closed stale tracking issue 3. ✅ Root Cause Analysis: Completed automated failure analysis -4. 🔄 Manual Intervention: Required per recommendations +4. 🔴 Manual Intervention: Required per recommendations ## Recommended Next Steps [Specific recommendations based on failure analysis] @@ -136,7 +159,7 @@ for issue in automation_tracking_issues: expected_interval = get_expected_interval(issue.agent_prefix, issue.type) time_since_creation = now() - issue.created_at staleness_threshold = expected_interval * 1.2 # 20% tolerance - + if time_since_creation > staleness_threshold: mark_agent_as_stalled(issue.agent_prefix) trigger_recovery_actions(issue.agent_prefix, issue) @@ -173,19 +196,19 @@ All tracking issues MUST start with this standardized header: --- -**Automated by CleverAgents Bot** +**Automated by CleverAgents Bot** Supervisor: | Agent: ``` ### Template Variables -- **``**: The agent type (e.g., "implementation-orchestrator", "backlog-groomer") +- **``**: The agent type (e.g., "implementation-orchestrator", "backlog-groomer") - **``**: Current cycle number for this agent - **``**: Expected time between reports (e.g., "5 minutes", "10 cycles") - **``**: When the next report is expected (ISO 8601 format) - **``**: Current agent health status - `active`: Normal operation - - `warning`: Non-critical issues detected + - `warning`: Non-critical issues detected - `error`: Critical issues requiring attention ## Implementation Requirements @@ -196,7 +219,7 @@ Every agent that creates tracking issues must implement: 1. **Cleanup Function**: Delete previous cycle tracking issues before creating new ones 2. **Standardized Titles**: Use the exact format specified above -3. **Proper Labels**: Always include "Automation Tracking" label +3. **All Required Labels**: Always include all four required labels (see [Required Labels](#required-labels)) 4. **Structured Content**: Use consistent formatting for issue bodies ### Standard Tracking Functions @@ -214,7 +237,7 @@ Each agent should implement these functions: ### Create New Tracking Issue 1. Generate title with current cycle number -2. Include "Automation Tracking" label +2. Apply all four required labels (Automation Tracking, Type/Automation, State/In Progress, Priority/Medium) 3. Add structured content with timestamp and status 4. Link to relevant repositories/PRs as needed ``` @@ -227,7 +250,7 @@ Each agent should implement these functions: - **Content**: Session state, active agents, configuration - **Cleanup**: Deletes previous checkpoint issue -#### implementation-orchestrator +#### implementation-orchestrator - **Cycle Frequency**: Health reports every 10 cycles, status every 5 cycles - **Issue Types**: Health Report, Status Update - **Content**: Worker status, queue health, completion metrics @@ -247,10 +270,16 @@ Each agent should implement these functions: #### human-liaison - **Cycle Frequency**: Status every 10 cycles -- **Issue Types**: Status Update, Human Activity Summary +- **Issue Types**: Status Update, Human Activity Summary - **Content**: Human interactions, triage decisions, outstanding items - **Cleanup**: Deletes previous status updates +#### docs-writer +- **Cycle Frequency**: Documentation report every 10 cycles (~3.3 hours) +- **Issue Types**: Documentation Report +- **Content**: Docs created/updated/skipped, commit hash, next actions +- **Cleanup**: Closes previous documentation report issue + ## Searching and Filtering ### Finding Tracking Issues @@ -267,6 +296,7 @@ label:"Automation Tracking" [AUTO-IMP-POOL] in:title label:"Automation Tracking" [AUTO-WATCHDOG] in:title label:"Automation Tracking" [AUTO-GROOMER] in:title label:"Automation Tracking" [AUTO-LIAISON] in:title +label:"Automation Tracking" [AUTO-DOCS] in:title ``` **Recent tracking issues (last 24 hours):** @@ -309,6 +339,11 @@ If tracking issues accumulate excessively: - Check agent permission to add labels - Verify label name spelling (case sensitive) +**Missing Type/Automation, State/In Progress, or Priority/Medium labels:** +- All four labels are required on every tracking issue +- Use the numeric label IDs (1398, 1397, 843, 860) when applying via API +- The `forgejo-label-manager` subagent can validate label compliance + **Tracking issues not being cleaned up:** - Check if agent cleanup function is running - Verify backlog-groomer is active and functioning @@ -328,7 +363,7 @@ If tracking issues accumulate excessively: 1. **Check agent status**: Verify agent is running and healthy 2. **Verify title format**: Ensure exact compliance with format standards -3. **Check labels**: Confirm "Automation Tracking" label is applied +3. **Check labels**: Confirm all four required labels are applied 4. **Review cleanup logs**: Look for cleanup function errors 5. **Manual search**: Use repository issue search to verify tracking issues @@ -350,4 +385,4 @@ The migration was completed by updating agent definitions in `.opencode/agents/` - [System Watchdog](system-watchdog.md) - Specific documentation for watchdog agent - [Quality Automation](quality-automation.md) - Quality gate automation details -- [Ops Runbook](ops-runbook.md) - General operational procedures \ No newline at end of file +- [Ops Runbook](ops-runbook.md) - General operational procedures -- 2.52.0 From 9723c701170ee672987a8d448898b8ac8d4d313a Mon Sep 17 00:00:00 2001 From: HAL 9000 Date: Thu, 9 Apr 2026 08:49:40 +0000 Subject: [PATCH 2/2] docs(changelog): add plan action-arguments bug fix and docs-writer tracking Documents the fix for UNIQUE constraint violation in ActionRepository.update() when using agents plan use with pre-existing action arguments. Also documents the docs-writer agent tracking issue format in the Automation Tracking section. --- CHANGELOG.md | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 885d0e7ba..e52ed5e69 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -34,12 +34,23 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). PR–issue label synchronization. The `issue-state-updater` syncs PR state labels whenever issue states change. +- **Automation Tracking Required Labels**: All automation tracking issues now require four + labels: `Automation Tracking`, `Type/Automation`, `State/In Progress`, and + `Priority/Medium`. Label IDs: 1398, 1397, 843, 860 respectively. + ### Changed - **Automation Tracking Format**: All automation tracking issues now use a standardized header format with mandatory `Reporting Interval: (Next report expected: )` declarations, enabling precise staleness detection. +### Fixed + +- `ActionRepository.update()` now uses explicit bulk `sa_delete()` + `session.flush()` + before re-inserting child rows for `action_arguments` and `action_invariants`, fixing + a `sqlite3.IntegrityError: UNIQUE constraint failed` crash when `agents plan use` was + called on an action that already had arguments registered via `action create`. (#4197) + --- ## [3.8.0] — 2026-04-05 -- 2.52.0