DEVX-164: fix(ci): retry Vikunja lookups and surface self-approval merge failures

docs/specs/DEVX-164-docker-push-retry-historical.md

@@ -0,0 +1,34 @@
+# DEVX-164: Increase HTTP 500 retry count and backoff for docker push
+
+## Problem
+The HTTP 500 retry logic (DEVX-162, DEVX-163) works correctly — 3 retry
+attempts are made. But all 3 attempts fail because the Gitea registry's
+"offset mismatch" race condition needs more than ~15s to recover. The
+current backoff is 5s-20s with 3 attempts (total ~15s of waiting).
+
+## Approach
+Increase retry count from 3 to 5 and backoff from 5-20s to 10-60s,
+giving the registry up to ~2 minutes to recover. Add visible logging
+between retry attempts so the CI logs show the retry happening.
+
+REQ-1: Increase retry count from 3 to 5
+REQ-2: Increase backoff from 5-20s to 10-60s exponential
+REQ-3: Add visible logging between retry attempts (click.echo)
+REQ-4: All tests pass with 100% coverage
+
+## Test Plan
+- Unit tests verify retry count and backoff parameters
+- Unit tests verify logging output on retry
+- Manual: trigger build-images workflow and verify retries visible in logs
+
+## Deploy Plan
+- Merge to master
+
+## Rollback Plan
+- Revert the merge commit
+
+## Acceptance Criteria
+- [x] REQ-1: Increase retry count from 3 to 5
+- [x] REQ-2: Increase backoff from 5-20s to 10-60s exponential
+- [x] REQ-3: Add visible logging between retry attempts (click.echo)
+- [x] REQ-4: All tests pass with 100% coverage

docs/specs/DEVX-164.md

@@ -1,34 +1,57 @@
-# DEVX-164: Increase HTTP 500 retry count and backoff for docker push
+# DEVX-164: auto-merge resilience — self-approval and Vikunja outage handling
 
 ## Problem
-The HTTP 500 retry logic (DEVX-162, DEVX-163) works correctly — 3 retry
-attempts are made. But all 3 attempts fail because the Gitea registry's
-"offset mismatch" race condition needs more than ~15s to recover. The
-current backoff is 5s-20s with 3 attempts (total ~15s of waiting).
+
+Two defects hit auto-merge during S02 work:
+
+1. `get_vikunja_task_title` crashes on transient Vikunja errors. The
+   Vikunja API returned 404/502 during a restart window (run 6093);
+   `list_project_tasks` treats 4xx as non-retryable `APIError`, so the
+   job failed immediately instead of riding out a short outage.
+2. When a PR author and the workflow's reviewer token map to the same
+   Gitea user, the auto-approve step is rejected ("approve your own
+   pull is not allowed") and the merge fails `405: not enough
+   approvals`. The generic merge error gives no hint that an external
+   approval is the fix (hit on sso-bridge #18, #19, and infra #1647's
+   approvals-only failure mode).
 
 ## Approach
-Increase retry count from 3 to 5 and backoff from 5-20s to 10-60s,
-giving the registry up to ~2 minutes to recover. Add visible logging
-between retry attempts so the CI logs show the retry happening.
 
-REQ-1: Increase retry count from 3 to 5
-REQ-2: Increase backoff from 5-20s to 10-60s exponential
-REQ-3: Add visible logging between retry attempts (click.echo)
-REQ-4: All tests pass with 100% coverage
+REQ-1: Wrap the task-list pagination in `get_vikunja_task_title` with a
+bounded retry (tenacity, ~4 attempts, exponential backoff) covering
+`APIError` and `requests.RequestException`. A genuinely missing task
+still ends in the same "Could not find" ClickException.
+
+REQ-2: On merge `HTTP 405`, fetch PR reviews; when zero `APPROVED`
+reviews exist, extend the error with the self-approval explanation and
+the remediation (approve via a non-author account).
+
+REQ-3: Regression tests for both behaviors.
+
+## Files Affected
+
+- `src/devx/ci/auto_merge.py`
+- `tests/unit/test_auto_merge.py`
 
 ## Test Plan
-- Unit tests verify retry count and backoff parameters
-- Unit tests verify logging output on retry
-- Manual: trigger build-images workflow and verify retries visible in logs
+
+- New tests: retry-then-success on transient APIError; retry-exhaustion
+  still raises; missing task still raises; 405 error includes
+  approvals diagnostic.
+- `make pytest-cov`, `make lint-all`.
 
 ## Deploy Plan
-- Merge to master
+
+- Merge → next release publishes the package; consuming repos pick it
+  up on their next CI run (devx is pinned per-repo, bump via the usual
+  dependency PR flow).
 
 ## Rollback Plan
-- Revert the merge commit
+
+- Revert; previous behavior returns.
 
 ## Acceptance Criteria
-- [x] REQ-1: Increase retry count from 3 to 5
-- [x] REQ-2: Increase backoff from 5-20s to 10-60s exponential
-- [x] REQ-3: Add visible logging between retry attempts (click.echo)
-- [x] REQ-4: All tests pass with 100% coverage
+
+- [x] REQ-1: Vikunja task-list retries transient API failures
+- [x] REQ-2: 405 merge error reports approval state + self-approval hint
+- [x] REQ-3: Regression tests added and passing