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

@@ -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: <interval> (Next report expected: <ts>)`
   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

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/<owner>/<repo>/issues/<number>/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> Agent Failure Analysis`
@@ -110,7 +133,7 @@ When a stalled agent is detected:
 
 **Agent Prefix**: <prefix>
 **Detection Time**: <ISO timestamp>
-**Stale Issue**: #<issue_number>  
+**Stale Issue**: #<issue_number>
 **Time Overdue**: <minutes> minutes
 **Staleness Ratio**: <ratio>x expected interval
 
@@ -119,9 +142,9 @@ When a stalled agent is detected:
 
 ## Recovery Actions Taken
 1. ✅ Session Termination: Killed <count> 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:
 <Planned actions for next cycle>
 
 ---
-**Automated by CleverAgents Bot**  
+**Automated by CleverAgents Bot**
 Supervisor: <supervisor-name> | Agent: <agent-name>
 ```
 
 ### Template Variables
 
-- **`<agent-name>`**: The agent type (e.g., "implementation-orchestrator", "backlog-groomer")  
+- **`<agent-name>`**: The agent type (e.g., "implementation-orchestrator", "backlog-groomer")
 - **`<cycle-number>`**: Current cycle number for this agent
 - **`<interval>`**: Expected time between reports (e.g., "5 minutes", "10 cycles")
 - **`<next-timestamp>`**: When the next report is expected (ISO 8601 format)
 - **`<status>`**: 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
+- [Ops Runbook](ops-runbook.md) - General operational procedures