release: v0.51.8 [skip ci]

Co-authored-by: emil User <emil.simeonov@tutanota.com>

.devin/skills/devx-workflow/SKILL.md

@@ -12,7 +12,6 @@ Quick reference for devx tools when working on the devx repo itself.
 | Check CI status | `make devx-pr-status` or `make devx-pr-status PR=42 WAIT=1` |
 | Fetch CI failure logs | `make devx-pr-logs` or `make devx-pr-logs PR=42 JOB=quality TAIL=50` |
 | Add ready-to-merge label | `make devx-pr-label` or `make devx-pr-label PR=42` |
-| Post PR review | `make devx-pr-review PR=42 EVENT=APPROVE BODY="..." CHECKLIST=1,2,3,4,5,6,7,8,9,10,11,12,13` |
 | Rebase current branch | `make rebase` |
 | Rebase PR via API | `make pr-rebase` or `make pr-rebase PR=42` |
 
@@ -24,6 +23,15 @@ When the `ready-to-merge` label is added and all CI checks pass:
 3. The rebase triggers a new CI run; the next auto-merge attempt merges
 4. No manual rebase needed unless the API rebase fails
 
+## Spec-Driven CI Gates (Pre-merge)
+
+Every PR must pass these gates before merge:
+
+| Gate | Module | What it checks |
+|------|--------|----------------|
+| Spec validation | `devx.ci.validate_spec` | Spec file exists at `docs/specs/<TASK-ID>.md`, has REQ-IDs, all ACs checked |
+| PR size | `devx.ci.check_pr_size` | Max 500 lines / 10 files (excludes CHANGELOG, badges, locks) |
+
 ## Key Rules
 
 - Never manually merge via API — always use auto-merge with `ready-to-merge` label

.devin/skills/pr-review/SKILL.md

@@ -0,0 +1,272 @@
+# pr-review
+
+Deep, critical PR review with auto-fix. This skill guides the agent
+through a thorough review of a pull request, posting inline comments
+for each issue found, auto-fixing them, resolving the discussion threads,
+and marking the PR as ready-to-merge when no blocking issues remain.
+
+## When to Invoke
+
+Invoke this skill when asked to review a PR, or when a PR is open and
+needs review before merge. Do NOT invoke automatically on every PR —
+this is an on-demand deep review, not a CI gate.
+
+## Prerequisites
+
+- The PR must be open in a Gitea repo
+- The agent needs Gitea MCP access (gitea server)
+- The agent needs git push access to the PR's head branch
+- The PR should have passed CI (validate job) before deep review
+
+## Review Categories
+
+Review every PR against these 8 categories. For each issue found, post
+an inline comment on the specific line, then auto-fix it.
+
+### 1. Functional Correctness
+
+- Does the code actually do what the spec/PR title claims?
+- Are edge cases handled? (empty input, null, boundary values, concurrent access)
+- Are error paths tested? Not just happy path.
+- Does the code handle all return values? (ignored errors, unchecked None)
+- Are there off-by-one errors, wrong comparisons, inverted conditions?
+- Do loops terminate correctly? (no infinite loops, correct break/continue)
+- Are regex patterns correct? (anchored, escaped, non-greedy where needed)
+- Are API responses validated before use? (status codes, response shape)
+
+### 2. Completeness
+
+- Are all requirements from the spec implemented? (check each REQ-ID)
+- Are all acceptance criteria in the spec checked off?
+- Are tests written for all new code paths?
+- Are error messages user-facing (wrapped in `_()`)?
+- Are new CLI commands documented in `docs/user/cli-commands.md`?
+- Are new modules added to architecture docs?
+- Are CHANGELOG entries added for user-facing changes?
+- Are translations added for new user-facing strings?
+
+### 3. Architecture
+
+- Does the code follow the repo's layer separation? (no business logic in CLI, no direct subprocess in CLI)
+- Are new dependencies justified? (no unnecessary new packages)
+- Is configuration via env vars / config.py, not hardcoded?
+- Are new modules placed in the correct directory? (ci/ vs tools/ vs molecule/)
+- Does the code reuse existing utilities? (no reimplemented helpers)
+- Are imports circular? (check import chains)
+- Is the code testable? (injectable dependencies, no hidden global state)
+- Does the code follow existing patterns in the codebase?
+
+### 4. Reliability
+
+- Are external API calls retried with backoff?
+- Are timeouts set on all network operations?
+- Are file operations atomic? (write to temp, rename)
+- Are database operations transactional where needed?
+- Are there race conditions? (check shared mutable state)
+- Are resources cleaned up in all paths? (finally blocks, context managers)
+- Can the code handle partial failures? (one service down, others up)
+- Are idempotency guarantees maintained? (safe to retry)
+
+### 5. Robustness
+
+- Does the code fail gracefully? (meaningful error messages, not stack traces)
+- Are unexpected inputs handled? (type checking, validation)
+- Are there any crash-on-bad-input paths?
+- Does the code degrade under load? (backpressure, queue limits)
+- Are there resource leaks? (file handles, connections, memory)
+- Does the code survive network partitions? (retry, circuit breaker)
+- Are there any unhandled exceptions that could crash the process?
+- Is logging sufficient to diagnose production issues?
+
+### 6. Security
+
+- Are there hardcoded secrets, tokens, or passwords?
+- Is `shell=True` used with user input? (command injection)
+- Is `eval()` or `exec()` used? (code injection)
+- Are SQL queries parameterized? (no string concatenation)
+- Are file paths validated? (no path traversal)
+- Are user inputs sanitized before display? (XSS in web contexts)
+- Are SSL/TLS verifications disabled without justification?
+- Are secrets logged in error messages or debug output?
+- Are permissions checked before privileged operations?
+- Is sensitive data in memory longer than necessary?
+
+### 7. Technical Excellence
+
+- Are functions under 50 lines? (refactor if longer)
+- Is cyclomatic complexity reasonable? (no deeply nested if/else chains)
+- Are names meaningful? (no single-letter vars, no misleading names)
+- Is dead code removed? (no commented-out blocks, no unused imports)
+- Are comments explaining WHY, not WHAT?
+- Is the code DRY? (no copy-pasted blocks that should be shared)
+- Is the code SOLID? (single responsibility, open/closed)
+- Are magic numbers extracted to named constants?
+- Is the code formatted per the repo's linter config?
+- Are type hints present on all function signatures?
+
+### 8. Test Quality
+
+- Do tests actually test the behavior? (not just that code runs)
+- Are tests independent? (no shared mutable state, no order dependency)
+- Are tests fast? (no real sleeps, no real network calls, mocked)
+- Are edge cases tested? (empty, None, boundary, error paths)
+- Are test names descriptive? (test_what_condition_expected_result)
+- Are mocks set up correctly? (mocking the right object, not too broad)
+- Is coverage 100% for new code? (every branch, every line)
+- Are integration tests added for cross-module changes?
+- Do tests clean up after themselves? (tmp_path, fixtures)
+
+## Review Procedure
+
+### Step 1: Gather Context
+
+```
+1. Read the PR spec (if exists): docs/specs/<TASK-ID>.md
+2. Fetch PR details via Gitea MCP: pull_request_read (get_pr, list_pr_files)
+3. Read the full diff: git diff origin/master...HEAD
+4. Read the PR description and any existing review comments
+5. Identify the repo's task prefix (OBL-INFRA, GRM, SSO, DEVX)
+```
+
+### Step 2: Review Each File
+
+For each changed file in the PR:
+
+1. Read the full file (not just the diff) to understand context
+2. Go through all 8 review categories
+3. For each issue found, note: file path, line number, category, severity, description, suggested fix
+
+### Step 3: Post Inline Comments
+
+For each issue found, post an inline review comment using the Gitea MCP:
+
+```
+mcp_call_tool: gitea / pull_request_review_write
+  method: create
+  owner: <owner>
+  repo: <repo>
+  pull_number: <PR number>
+  state: PENDING  (accumulate comments before submitting)
+  body: ""  (empty for now, summary added on submit)
+  comments: [
+    {
+      path: "<file path>",
+      new_line_num: <line number>,
+      body: "**[<category>] [<severity>]** <description>\n\n**Suggested fix:**\n```<lang>\n<fixed code>\n```"
+    }
+  ]
+```
+
+Comment format:
+```
+**[Security] [error]** `shell=True` used with user input — command injection risk.
+
+**Suggested fix:**
+```python
+subprocess.run(["git", "log", commit], check=True)
+```
+```
+
+Severity levels:
+- `error` — must fix before merge (security, correctness, crash)
+- `warning` — should fix before merge (reliability, best practice)
+- `info` — consider fixing (style, minor improvement)
+
+### Step 4: Auto-Fix Issues
+
+For each issue that can be safely auto-fixed:
+
+1. Edit the file using the `edit` tool
+2. Commit with message: `fix: address review comment — <short description>`
+3. Push to the PR's head branch: `git push origin HEAD`
+4. Wait for CI to re-run on the push
+
+Auto-fix ALL issues unless:
+- The fix requires an architectural decision (ask the user)
+- The fix changes public API behavior (ask the user)
+- The fix is ambiguous (multiple valid approaches, ask the user)
+
+### Step 5: Resolve Discussion Threads
+
+After auto-fixing an issue and CI passes:
+
+1. Find the review comment thread for that issue
+2. Post a reply: `Fixed in <commit-sha>. Closing this thread.`
+3. Resolve the discussion (if Gitea supports it via API)
+4. If resolving via API is not available, the reply comment serves as resolution
+
+### Step 6: Submit Final Review
+
+After all issues are addressed (fixed or discussed):
+
+```
+mcp_call_tool: gitea / pull_request_review_write
+  method: submit
+  owner: <owner>
+  repo: <repo>
+  pull_number: <PR number>
+  review_id: <from step 3 create>
+  state: COMMENT  (or APPROVED if no blocking issues remain)
+  body: <summary — see below>
+```
+
+### Step 7: Post Summary
+
+Post a brief summary as a PR comment (via `issue_write / add_comment`):
+
+```
+## Deep Review Summary
+
+- **Files reviewed:** N
+- **Issues found:** N (N auto-fixed, N require attention)
+- **Categories:** security (N), correctness (N), architecture (N), ...
+
+**Outcome:** ✅ Ready to merge — all issues addressed.
+**OR**
+**Outcome:** ⚠️ N blocking issue(s) remain — see inline comments.
+```
+
+Keep the summary to 5-10 bullet points. Do not paste the full review.
+
+### Step 8: Mark PR Ready
+
+If all issues are addressed and no blocking issues remain:
+
+```
+mcp_call_tool: gitea / issue_write
+  method: add_labels
+  owner: <owner>
+  repo: <repo>
+  issue_number: <PR number>
+  labels: [<label_id for "ready-to-merge">]
+```
+
+If blocking issues remain, do NOT add the label. Post a comment
+explaining what needs to be resolved before the PR can merge.
+
+## Gitea MCP Tools Reference
+
+| Action | MCP tool | Method |
+|--------|----------|--------|
+| Get PR details | `pull_request_read` | `get_pr` |
+| List PR files | `pull_request_read` | `list_pr_files` |
+| Get PR diff | `pull_request_read` | `get_pr_diff` |
+| Create review (pending) | `pull_request_review_write` | `create` (state: PENDING) |
+| Submit review | `pull_request_review_write` | `submit` (state: APPROVED/COMMENT/REQUEST_CHANGES) |
+| Post PR comment | `issue_write` | `add_comment` |
+| Add label | `issue_write` | `add_labels` |
+| List labels | `label_read` | `list_repo_labels` |
+| Merge PR | `pull_request_write` | `merge` (do NOT use — auto-merge handles this) |
+
+## Important Rules
+
+- **Never merge the PR yourself.** Add the `ready-to-merge` label and let
+  the auto-merge workflow handle it. This ensures CI passes and the
+  commit message follows the `<PREFIX>-N: <conventional>` format.
+- **Never approve your own PR.** If the agent created the PR, post
+  COMMENT state, not APPROVED.
+- **Always push fixes to the PR branch**, not directly to master.
+- **Wait for CI after each push** before resolving the discussion thread.
+- **Post one review with all comments**, not multiple reviews.
+- **The summary must be brief** — 5-10 bullet points max.
+- **Severity matters**: only `error` severity blocks the `ready-to-merge` label.

.devin/skills/spec-driven-development/SKILL.md

@@ -0,0 +1,130 @@
+# Spec-Driven Development
+
+## Overview
+
+Every change starts with a spec. No spec, no code. No code, no PR.
+
+The spec is a markdown file at `docs/specs/<TASK-ID>.md` in the repo.
+It contains structured requirements (REQ-IDs) and acceptance criteria
+(AC checklist) that CI validates before merge.
+
+## Workflow
+
+1. **Create Vikunja task** — `make create-task -- --title "Title" --description "..."`
+2. **Write spec** — Create `docs/specs/<TASK-ID>.md` (see template below)
+3. **Create branch** — `git checkout -b <PREFIX>-N-short-description`
+4. **Implement** — Write code with `# Implements: REQ-N` comments
+5. **Check ACs** — Tick all acceptance criteria checkboxes in the spec
+6. **Push and create PR** — `make push-with-pr`
+7. **CI validates** — Spec validation, PR size check, fast molecule, lint, tests
+8. **Auto-merge** — Add `ready-to-merge` label after review
+9. **Auto-deploy** — Post-merge deploys to staging (if nightly gate is green)
+
+## Spec Template
+
+```markdown
+# <TASK-ID>: <Title>
+
+## Problem
+<What is broken or missing? Why does this change exist?>
+
+## Approach
+<How will you solve it? What are the key design decisions?>
+
+REQ-1: <First requirement description>
+REQ-2: <Second requirement description>
+REQ-3: <Third requirement description>
+
+## Test Plan
+- <How will you verify each REQ is implemented correctly?>
+- <Include unit tests, molecule scenarios, integration tests>
+
+## Deploy Plan
+- <How will this change be deployed?>
+- <What order do components need to deploy in?>
+- <Are there migrations or one-time operations?>
+
+## Rollback Plan
+- <How do you revert if something goes wrong?>
+- <What data/state changes are irreversible?>
+
+## Acceptance Criteria
+- [ ] REQ-1: <criterion that proves REQ-1 is done>
+- [ ] REQ-2: <criterion that proves REQ-2 is done>
+- [ ] REQ-3: <criterion that proves REQ-3 is done>
+```
+
+## CI Validation
+
+The `devx.ci.validate_spec` module checks:
+
+1. **Spec file exists** at `docs/specs/<TASK-ID>.md` (TASK-ID from branch name)
+2. **Required sections present**: Problem, Approach, Test Plan, Deploy Plan, Rollback Plan, Acceptance Criteria
+3. **At least one REQ-ID** line (format: `REQ-N: <description>`)
+4. **All AC checkboxes checked** (`- [x]`, not `- [ ]`)
+
+If any check fails, CI blocks the PR before expensive jobs run.
+
+## PR Size Limits
+
+CI enforces max 500 lines / 10 files changed (excluding CHANGELOG.md,
+README.md, badges, lock files). Oversized PRs are rejected. Split your
+work into smaller PRs.
+
+## Code-to-Spec Linking
+
+Each function, task, or template that implements a requirement should
+have a comment:
+
+```python
+# Implements: REQ-1
+def install_sso_bridge():
+    ...
+```
+
+```yaml
+# Implements: REQ-2
+- name: Clone infra repo
+  git:
+    ...
+```
+
+## Fast Molecule (Pre-merge)
+
+CI runs molecule only for **changed roles** (detected via git diff),
+with converge + verify only, single platform. This gives quick feedback
+(~5-10 min) without the full molecule suite.
+
+## Full Molecule (Nightly)
+
+The complete molecule suite (all scenarios, all platforms) runs nightly
+at 02:00 CET on master. If it fails:
+- A Gitea issue is created with the `feedback` label
+- The `NIGHTLY_STATUS` repo variable is set to `failed:<run_id>`
+- All staging deploys are blocked until nightly passes again
+
+## Auto-Deploy on Merge
+
+Every merged PR auto-deploys to staging (if nightly gate is green).
+No manual trigger needed. The deploy runs the full pipeline:
+provision → deploy-observability → deploy-customer → configure-oidc.
+
+For grm/sso-bridge: post-merge publishes the package, then auto-creates
+an infra PR to bump the pinned version. That infra PR auto-deploys when
+merged.
+
+## Key Commands
+
+```bash
+# Validate spec locally (before pushing)
+python -m devx.ci.validate_spec --branch <PREFIX>-N-description
+
+# Check PR size locally
+python -m devx.ci.check_pr_size --base origin/master --head HEAD
+
+# See which roles need fast molecule
+python -m devx.ci.fast_molecule --base origin/master --head HEAD
+
+# Check nightly gate status
+python -m devx.ci.nightly_gate --repo oblachno/infra --action check
+```

.devin/skills/testing-and-debugging/SKILL.md

@@ -45,6 +45,13 @@ This runs `lint-all` + `pytest-cov`. The pre-push git hook only
 validates the Vikunja task exists — it does NOT run tests. You must
 run `make pre-push` manually.
 
+### Spec-Driven Workflow
+
+Every PR requires a spec file at `docs/specs/<TASK-ID>.md`. See the
+`spec-driven-development` skill for the full workflow and template.
+CI validates the spec (via `devx.ci.validate_spec`) and checks PR size
+(via `devx.ci.check_pr_size`) before running expensive jobs.
+
 ## CI Failure Investigation
 
 When investigating a CI failure:

.gitea/workflows/build-images.yml

@@ -32,6 +32,11 @@ concurrency:
 jobs:
   build-and-push:
     runs-on: docker
+    container:
+      image: git.oblachno.oblachno.fyi/oblachno-oss/runner-images/ci-full:latest
+      credentials:
+        username: ${{ vars.CI_GITEA_USERNAME }}
+        password: ${{ secrets.CI_GITEA_API_TOKEN }}
     timeout-minutes: 30
     outputs:
       is-release: ${{ steps.check.outputs.is-release }}
@@ -72,6 +77,9 @@ jobs:
           CI_GITEA_API_TOKEN: ${{ secrets.CI_GITEA_API_TOKEN }}
           CI_GITEA_USERNAME: ${{ vars.CI_GITEA_USERNAME }}
           PYTHONPATH: src
+          # Serialize blob uploads to avoid Gitea registry race condition
+          # (BlobUploader.Append offset mismatch — see DEVX-162).
+          DOCKER_MAX_CONCURRENT_UPLOADS: "1"
         run: |
           . .venv/bin/activate
           export PATH="$HOME/.local/bin:$PATH"
@@ -115,6 +123,11 @@ jobs:
     needs: [build-and-push]
     if: always() && needs.build-and-push.result == 'success'
     runs-on: docker
+    container:
+      image: git.oblachno.oblachno.fyi/oblachno-oss/runner-images/ci-base:latest
+      credentials:
+        username: ${{ vars.CI_GITEA_USERNAME }}
+        password: ${{ secrets.CI_GITEA_API_TOKEN }}
     timeout-minutes: 10
     steps:
       - uses: actions/checkout@v4

.gitea/workflows/ci.yml

@@ -18,7 +18,11 @@ jobs:
   # Saves ~4x checkout+setup overhead vs 5 separate jobs.
   validate:
     runs-on: docker
-    container: git.oblachno.oblachno.fyi/oblachno-oss/runner-images/ci-full:latest
+    container:
+      image: git.oblachno.oblachno.fyi/oblachno-oss/runner-images/ci-full:latest
+      credentials:
+        username: ${{ vars.CI_GITEA_USERNAME }}
+        password: ${{ secrets.CI_GITEA_API_TOKEN }}
     timeout-minutes: 15
     defaults:
       run:
@@ -46,7 +50,7 @@ jobs:
       - name: Check unit test speed
         run: |
           . .venv/bin/activate 2>/dev/null || true
-          python3 -m devx.tools.check_test_speed --max-seconds 6 --max-single-seconds 0.5
+          python3 -m devx.tools.check_test_speed --max-seconds 15 --max-single-seconds 0.5
       - name: Documentation gate (coverage + stale refs + lint + version refs + prose)
         env:
           DEVX_DOC_COVERAGE_STRICT: "1"
@@ -102,14 +106,30 @@ jobs:
             --pr-title "$PR_TITLE" \
             --repo "$REPOSITORY" \
             --pr-number "$PR_NUMBER"
-      - name: Run automated PR review
+      - name: Validate spec file
         if: github.event_name == 'pull_request'
+        env:
+          DEVX_TASK_PREFIX: DEVX
+          PYTHONPATH: ${{ env.PYTHONPATH }}
+          HEAD_REF: ${{ github.head_ref }}
         run: |
           . .venv/bin/activate 2>/dev/null || true
-          set -euo pipefail
-          python3 -m devx.ci.pr_review \
-            "${{ github.event.number }}" \
-            "${{ github.repository }}"
+          python3 -m devx.ci.validate_spec \
+            --branch "$HEAD_REF" \
+            --github-output
+      - name: Check PR size
+        if: github.event_name == 'pull_request'
+        env:
+          PYTHONPATH: ${{ env.PYTHONPATH }}
+          CI_GITEA_API_TOKEN: ${{ secrets.CI_GITEA_API_TOKEN }}
+        run: |
+          . .venv/bin/activate 2>/dev/null || true
+          python3 -m devx.ci.check_pr_size \
+            --base "origin/master" \
+            --head "${{ github.event.pull_request.head.sha || github.sha }}" \
+            --repo "${{ github.repository }}" \
+            --pr-number "${{ github.event.number }}" \
+            --github-output
       # --- release-dry-run step (conditional) ---
       - name: Release dry-run validation
         if: steps.detect.outputs.user-facing-changed == 'true'
@@ -140,7 +160,11 @@ jobs:
       github.event_name == 'pull_request' &&
       needs.validate.result == 'success'
     runs-on: docker
-    container: git.oblachno.oblachno.fyi/oblachno-oss/runner-images/ci-base:latest
+    container:
+      image: git.oblachno.oblachno.fyi/oblachno-oss/runner-images/ci-base:latest
+      credentials:
+        username: ${{ vars.CI_GITEA_USERNAME }}
+        password: ${{ secrets.CI_GITEA_API_TOKEN }}
     timeout-minutes: 10
     defaults:
       run:
@@ -159,16 +183,29 @@ jobs:
           REVIEWER_GITEA_API_TOKEN: ${{ secrets.REVIEWER_GITEA_API_TOKEN }}
           CI_GITEA_API_TOKEN: ${{ secrets.CI_GITEA_API_TOKEN }}
           PR_NUMBER: ${{ github.event.number }}
-          REPOSITORY: ${{ github.repository }}
+          GITHUB_SERVER_URL: ${{ github.server_url }}
+          GITHUB_REPOSITORY: ${{ github.repository }}
         run: |
           . .venv/bin/activate 2>/dev/null || true
-          python3 -m devx.ci.pr_review \
-            "$PR_NUMBER" \
-            "$REPOSITORY" \
-            --event APPROVE \
-            --checklist-confirmed \
-            --checklist-categories 1,2,3,4,5,6,7,8,9,10,11,12,13 \
-            --body "Auto-approved: all CI checks passed (validate job)."
+          # Post APPROVE review via Gitea API to satisfy branch protection.
+          # Try REVIEWER_GITEA_API_TOKEN first; fall back to CI_GITEA_API_TOKEN
+          # (CI bot account) if the reviewer token is the same user as the PR
+          # creator (Gitea rejects self-approvals).
+          for TOKEN in "${REVIEWER_GITEA_API_TOKEN}" "${CI_GITEA_API_TOKEN}"; do
+            [ -z "$TOKEN" ] && continue
+            RESPONSE=$(curl -s -w "\n%{http_code}" -X POST \
+              "${GITHUB_SERVER_URL}/api/v1/repos/${GITHUB_REPOSITORY}/pulls/${PR_NUMBER}/reviews" \
+              -H "Authorization: token ${TOKEN}" \
+              -H "Content-Type: application/json" \
+              -d '{"event":"APPROVED","body":"Auto-approved: all CI checks passed (validate job)."}')
+            HTTP_CODE=$(echo "$RESPONSE" | tail -1)
+            BODY=$(echo "$RESPONSE" | head -n -1)
+            if [ "$HTTP_CODE" = "200" ] || [ "$HTTP_CODE" = "201" ]; then
+              echo "Approval posted successfully (HTTP $HTTP_CODE)."
+              break
+            fi
+            echo "::warning::Approval with token failed (HTTP $HTTP_CODE): ${BODY}"
+          done
       - name: Squash merge with task ID
         env:
           CI_GITEA_API_TOKEN: ${{ secrets.CI_GITEA_API_TOKEN }}

.gitea/workflows/post-merge.yml

@@ -35,7 +35,11 @@ env:
 jobs:
   detect-and-configure:
     runs-on: docker
-    container: git.oblachno.oblachno.fyi/oblachno-oss/runner-images/ci-base:latest
+    container:
+      image: git.oblachno.oblachno.fyi/oblachno-oss/runner-images/ci-base:latest
+      credentials:
+        username: ${{ vars.CI_GITEA_USERNAME }}
+        password: ${{ secrets.CI_GITEA_API_TOKEN }}
     timeout-minutes: 10
     defaults:
       run:
@@ -99,7 +103,11 @@ jobs:
     needs: [detect-and-configure]
     if: always() && needs.detect-and-configure.result == 'success'
     runs-on: docker
-    container: git.oblachno.oblachno.fyi/oblachno-oss/runner-images/ci-full:latest
+    container:
+      image: git.oblachno.oblachno.fyi/oblachno-oss/runner-images/ci-full:latest
+      credentials:
+        username: ${{ vars.CI_GITEA_USERNAME }}
+        password: ${{ secrets.CI_GITEA_API_TOKEN }}
     timeout-minutes: 15
     outputs:
       tag: ${{ steps.release-tag.outputs.tag }}

.pre-commit-config.yaml

@@ -59,7 +59,7 @@ repos:
 
       - id: check-test-speed
         name: unit test speed check
-        entry: .venv/bin/python -m devx.tools.check_test_speed --max-seconds 6 --max-single-seconds 0.5
+        entry: .venv/bin/python -m devx.tools.check_test_speed --max-seconds 15 --max-single-seconds 0.5
         language: system
         types: [python]
         pass_filenames: false

.vale/styles/Google/Anthropomorphism.yml

@@ -0,0 +1,12 @@
+extends: existence
+message: "Don't attribute human qualities to software or hardware ('%s')."
+link: https://developers.google.com/style/anthropomorphism
+level: suggestion
+ignorecase: true
+# Limited to the two verbs the guide itself names. Broader lists (wants, knows,
+# thinks) can't tell a software subject from a human one: on a 950-file corpus
+# they produced 8 false positives ('the customer wants', 'your audience knows')
+# for every 2 real ones.
+tokens:
+  - sees
+  - tells

.vale/styles/Google/Colons.yml

@@ -1,8 +1,13 @@
 extends: existence
 message: "'%s' should be in lowercase."
 link: 'https://developers.google.com/style/colons'
-nonword: true
 level: warning
 scope: sentence
+# The match is the word itself, not ': X', and `nonword` is off. Both are
+# required for a project Vocab to work: Vale compares accept.txt entries
+# against the matched text, and `nonword: true` opts out of that entirely.
+# So a proper noun after a colon can be exempted by adding it to accept.txt.
+# The guide's other exemption, notice labels, is handled by the lookbehinds;
+# headings are already excluded by `scope: sentence`. See issue #20.
 tokens:
-  - '(?<!:[^ ]+?):\s[A-Z]'
+  - '(?<!Note: )(?<!Caution: )(?<!Warning: )(?<!Success: )(?<=:\s)[A-Z]\w+'

.vale/styles/Google/DateFormat.yml

@@ -6,4 +6,4 @@ level: error
 nonword: true
 tokens:
   - '\d{1,2}(?:\.|/)\d{1,2}(?:\.|/)\d{4}'
-  - '\d{1,2} (?:Jan(?:uary)?|Feb(?:ruary)?|Mar(?:ch)?|Apr(?:il)|May|Jun(?:e)|Jul(?:y)|Aug(?:ust)|Sep(?:tember)?|Oct(?:ober)|Nov(?:ember)?|Dec(?:ember)?) \d{4}'
+  - '\d{1,2} (?:Jan(?:uary)?|Feb(?:ruary)?|Mar(?:ch)?|Apr(?:il)?|May|Jun(?:e)?|Jul(?:y)?|Aug(?:ust)?|Sep(?:tember)?|Oct(?:ober)?|Nov(?:ember)?|Dec(?:ember)?) \d{4}'

.vale/styles/Google/ExcessiveClaims.yml

@@ -0,0 +1,14 @@
+extends: existence
+message: "Avoid the unverifiable claim '%s'."
+link: https://developers.google.com/style/excessive-claims
+level: suggestion
+ignorecase: true
+# The guide also names 'never', 'always', and 'ensure', but in technical writing
+# those are usually legitimate instructions ('never commit secrets') rather than
+# product claims: they accounted for 125 of 142 hits on a 950-file corpus.
+# 'best practices' is a fixed term, not a superlative.
+tokens:
+  - 'best(?! practices?)'
+  - simplest
+  - fastest
+  - guarantees?

.vale/styles/Google/FirstPerson.yml

@@ -3,11 +3,13 @@ message: "Avoid first-person pronouns such as '%s'."
 link: 'https://developers.google.com/style/pronouns#personal-pronouns'
 ignorecase: true
 level: warning
-nonword: true
+# The 'I' tokens use lookaround rather than consuming the surrounding
+# whitespace. Matching ' I ' made the alert span cover both spaces, which shows
+# up as a too-wide underline in editors, and read as "such as ' I '". Dropping
+# `nonword` also lets a project Vocab apply, which it can't when set. See PR #50.
 tokens:
-  - (?:^|\s)I\s
-  - (?:^|\s)I,\s
-  - \bI'm\b
+  - '(?<=^|\s)I(?=[\s,])'
+  - "\\bI'm\\b"
   - \bme\b
   - \bmy\b
   - \bmine\b

.vale/styles/Google/Headings.yml

@@ -4,8 +4,11 @@ link: "https://developers.google.com/style/capitalization#capitalization-in-titl
 level: warning
 scope: heading
 match: $sentence
-indicators:
-  - ":"
+# No `indicators: [":"]` here. That makes Vale require a capital after a colon,
+# which is the Microsoft convention this rule was originally copied from. This
+# guide says the opposite: "the first word after a colon is generally
+# lowercase" (developers.google.com/style/colons), and Colons.yml enforces
+# exactly that. See issue #58.
 exceptions:
   - Azure
   - CLI

.vale/styles/Google/Jargon.yml

@@ -0,0 +1,13 @@
+extends: existence
+message: "Avoid the jargon '%s'."
+link: https://developers.google.com/style/jargon
+level: suggestion
+ignorecase: true
+# The guide also cites 'solution', 'support', and 'workload' as overloaded
+# terms, but those have ordinary technical meanings and accounted for every hit
+# on a 950-file corpus, so only the unambiguous figurative terms are listed.
+tokens:
+  - break-glass
+  - camel ?case
+  - out-of-the-box
+  - swim ?lane

.vale/styles/Google/Latin.yml

@@ -6,6 +6,10 @@ level: error
 nonword: true
 action:
   name: replace
+# The delimiter is a lookahead so the replacement doesn't swallow the comma or
+# space that follows (issue #18). `$` is included so the abbreviation is still
+# caught at the end of a heading, table cell, or block, which accounted for 8
+# of 10 occurrences on a 950-file corpus.
 swap:
-  '\b(?:eg|e\.g\.)(?=[\s,;])': for example
-  '\b(?:ie|i\.e\.)(?=[\s,;])': that is
+  '\b(?:eg|e\.g\.)(?=[\s,;]|$)': for example
+  '\b(?:ie|i\.e\.)(?=[\s,;]|$)': that is

.vale/styles/Google/OxfordComma.yml

@@ -3,5 +3,26 @@ message: "Use the Oxford comma in '%s'."
 link: 'https://developers.google.com/style/commas'
 scope: sentence
 level: warning
+nonword: true
+# List items may be several words long, not just one. Four guards keep the
+# false-positive rate down:
+#
+#   1. The comma can't be the one closing a fronted subordinate clause
+#      ('When your alarm rings, you turn it off and tumble out of bed.') --
+#      that comma separates clauses, not list items. Only the first comma of
+#      such a sentence is exempt, so 'When it rains, apples, pears or bananas
+#      get wet.' is still caught.
+#   2. The item can't open with a clause-introducer (', which ...',
+#      ', specifically ...').
+#   3. The item can't open with a subject pronoun followed by a verb, which
+#      marks a compound predicate rather than a list ('..., you walk to the
+#      fridge and get a snack.'). A pronoun directly followed by 'and'/'or'
+#      is a real list item, so ', you and me.' still matches.
+#   4. Neither item may contain an auxiliary verb, which is another compound
+#      predicate signal (', it has some downsides and is officially
+#      discouraged.').
+#
+# The trailing anchor allows end-of-scope so list fragments ('Apples, pears
+# or bananas') are still caught.
 tokens:
-  - '(?:[^,]+,){1,}\s\w+\s(?:and|or)'
+  - '(?<!^(?i:when|whenever|while|if|unless|until|although|though|because|since|after|before|once|whereas|whether|as)\b[^,]{0,80}),\s(?!(?:which|who|whom|whose|that|where|when|while|because|since|although|though|if|unless|so|but|and|or|however|therefore|thus|specifically|especially|namely|then|take|see|note|consider|make|use|either|neither)\b)(?!(?i:i|you|we|they|he|she|it)\s+(?!(?:and|or)\b))(?:(?!\b(?:is|are|was|were|has|have|had|be|been|being|will|would|can|could|should|may|might|must|do|does|did)\b)\w+ ){0,4}\w+ (?:and|or) (?:(?!\b(?:is|are|was|were|has|have|had|be|been|being|will|would|can|could|should|may|might|must|do|does|did)\b)\w+ ){0,4}\w+(?:[.?!]|$)'

.vale/styles/Google/Parens.yml

@@ -3,5 +3,13 @@ message: "Use parentheses judiciously."
 link: 'https://developers.google.com/style/parentheses'
 nonword: true
 level: suggestion
+# `[^)]` rather than `.+`: a greedy match ran from the first '(' on a line to
+# the last ')', so 'Text (one) and more (two).' produced a single alert
+# covering everything between them. See issue #30.
+# A bare 3-5 letter acronym is skipped: Acronyms.yml requires acronyms to be
+# defined as 'Spelled Out Term (ACRONYM)', so flagging those parentheses would
+# put the two rules in direct conflict. The acronym has to be the whole
+# parenthetical — '(NASA rocket program)' is an ordinary aside and still
+# flags. Length matches the {3,5} in Acronyms.yml. See PR #59.
 tokens:
-  - '\(.+\)'
+  - '\((?![A-Z]{3,5}\))[^)]+\)'

.vale/styles/Google/Timeless.yml

@@ -0,0 +1,13 @@
+extends: existence
+message: "Avoid time-based words like '%s' in product documentation."
+link: https://developers.google.com/style/timeless-documentation
+level: suggestion
+ignorecase: true
+# The guide also names 'now' and 'new', but both have common senses that aren't
+# time-anchored ('create a new project'): adding them took a 950-file corpus of
+# technical documentation from 14 hits to 117. 'recently' is left out too — every
+# hit in that corpus was the UI idiom 'recently used'.
+tokens:
+  - currently
+  - latest
+  - soon

.vale/styles/Google/Units.yml

@@ -4,5 +4,7 @@ link: "https://developers.google.com/style/units-of-measure"
 nonword: true
 level: error
 tokens:
-  - \b\d+(?:B|kB|MB|GB|TB)
-  - \b\d+(?:ns|ms|s|min|h|d)
+  - '\b\d+(?:B|kB|MB|GB|TB)\b'
+  - '\b\d+(?:ns|ms|min|h|d)\b'
+  # Seconds are split out so a decade ('1990s') isn't read as a unit.
+  - '\b\d+s\b(?<!\b(?:19|20)\d\ds\b)'

.vale/styles/Google/WordList.yml

@@ -2,79 +2,28 @@ extends: substitution
 message: "Use '%s' instead of '%s'."
 link: "https://developers.google.com/style/word-list"
 level: warning
+# Case matters here: each key's own capitalization is what's being corrected,
+# so ignorecase would make these match their own replacements. The rest of the
+# word list lives in WordListCase.yml.
 ignorecase: false
 action:
   name: replace
 swap:
-  "(?:API Console|dev|developer) key": API key
-  "(?:cell ?phone|smart ?phone)": phone|mobile phone
-  "(?:dev|developer|APIs) console": API console
-  "(?:e-mail|Email|E-mail)": email
-  "(?:file ?path|path ?name)": path
-  "(?:kill|terminate|abort)": stop|exit|cancel|end
-  "(?:OAuth ?2|Oauth)": OAuth 2.0
-  "(?:ok|Okay)": OK|okay
-  "(?:WiFi|wifi)": Wi-Fi
-  '[\.]+apk': APK
-  '3\-D': 3D
-  'Google (?:I\-O|IO)': Google I/O
-  "tap (?:&|and) hold": touch & hold
-  "un(?:check|select)": clear
-  above: preceding
-  account name: username
-  action bar: app bar
-  admin: administrator
   Ajax: AJAX
-  a\.k\.a|aka: or|also known as
   Android device: Android-powered device
   android: Android
   API explorer: APIs Explorer
-  application: app
-  approx\.: approximately
   authN: authentication
   authZ: authorization
-  autoupdate: automatically update
-  cellular data: mobile data
-  cellular network: mobile network
-  chapter: documents|pages|sections
-  check box: checkbox
   CLI: command-line tool
-  click on: click|click in
   Cloud: Google Cloud Platform|GCP
   Container Engine: Kubernetes Engine
-  content type: media type
-  curated roles: predefined roles
-  data are: data is
   Developers Console: Google API Console|API Console
-  disabled?: turn off|off
-  ephemeral IP address: ephemeral external IP address
-  fewer data: less data
-  file name: filename
-  firewalls: firewall rules
-  functionality: capability|feature
   Google account: Google Account
   Google accounts: Google Accounts
   Googling: search with Google
-  grayed-out: unavailable
   HTTPs: HTTPS
-  in order to: to
-  ingest: import|load
   k8s: Kubernetes
-  long press: touch & hold
-  network IP address: internal IP address
-  omnibox: address bar
-  open-source: open source
-  overview screen: recents screen
-  regex: regular expression
   SHA1: SHA-1|HAS-SHA1
-  sign into: sign in to
-  sign-?on: single sign-on
-  static IP address: static external IP address
-  stylesheet: style sheet
-  synch: sync
-  tablename: table name
-  tablet: device
-  touch: tap
   url: URL
-  vs\.: versus
   World Wide Web: web

.vale/styles/Google/WordListCase.yml

@@ -0,0 +1,68 @@
+extends: substitution
+message: "Use '%s' instead of '%s'."
+link: "https://developers.google.com/style/word-list"
+level: warning
+# The case-insensitive half of the word list, so sentence-initial use is caught
+# ('Touch the screen', not only 'touch the screen'). Entries that must stay
+# case-sensitive are in WordList.yml.
+ignorecase: true
+action:
+  name: replace
+swap:
+  "(?:API Console|dev|developer) key": API key
+  "(?:cell ?phone|smart ?phone)": phone|mobile phone
+  "(?:dev|developer|APIs) console": API console
+  "(?:e-mail|Email|E-mail)": email
+  "(?:file ?path|path ?name)": path
+  "(?:kill|terminate|abort)": stop|exit|cancel|end
+  # Longest form first: with the shortest alternative leading, 'OAuth 2' matched
+  # only 'OAuth', so applying the suggestion produced 'OAuth 2.0 2'. The rule is
+  # already case-insensitive, so the inline (?i) is redundant. See issue #41.
+  '\bOauth2\.0\b|\bOAuth ?2\b(?!\.0)|\bOauth\b(?! ?2)': OAuth 2.0
+  "(?:ok|Okay)": OK|okay
+  "(?:WiFi|wifi)": Wi-Fi
+  '[\.]+apk': APK
+  '3\-D': 3D
+  'Google (?:I\-O|IO)': Google I/O
+  "tap (?:&|and) hold": touch & hold
+  "un(?:check|select)": clear
+  above: preceding
+  account name: username
+  action bar: app bar
+  admin: administrator
+  a\.k\.a|aka: or|also known as
+  application: app
+  approx\.: approximately
+  autoupdate: automatically update
+  cellular data: mobile data
+  cellular network: mobile network
+  chapter: documents|pages|sections
+  check box: checkbox
+  click on: click|click in
+  content type: media type
+  curated roles: predefined roles
+  data are: data is
+  disabled?: turn off|off
+  ephemeral IP address: ephemeral external IP address
+  fewer data: less data
+  file name: filename
+  firewalls: firewall rules
+  functionality: capability|feature
+  grayed-out: unavailable
+  in order to: to
+  ingest: import|load
+  long press: touch & hold
+  network IP address: internal IP address
+  omnibox: address bar
+  open-source: open source
+  overview screen: recents screen
+  regex: regular expression
+  sign into: sign in to
+  '(?<!single )sign-?on': single sign-on
+  static IP address: static external IP address
+  stylesheet: style sheet
+  synch: sync
+  tablename: table name
+  tablet: device
+  'touch(?! ?(?:&|and) hold)': tap
+  vs\.: versus

AGENTS.md

@@ -28,6 +28,11 @@ make workflow-check  # workflow-lint + workflow-dryrun
 make devx-check-doc-versions  # Verify docs version refs match __version__
 make devx-vale       # Run Vale prose linter on docs and README
 make clean           # Remove caches, build artifacts, coverage data
+make check-workflow-artifact-deps  # Verify artifact download jobs depend on upload jobs
+make check-workflow-tofu-init      # Verify tofu-state jobs have a tofu-init step
+make check-docker-init             # Check Docker Compose services with healthchecks have init: true
+make check-ansible-set-fact-to-json  # Check set_fact tasks don't misuse to_json
+make check-alert-rules             # Validate Prometheus alert rules with promtool
 ```
 
 `make setup` automatically installs all development tools:
@@ -71,14 +76,13 @@ src/devx/
 ├── translations.json    # Translation strings (en, bg, de, pl, ru, zh)
 ├── ci/                  # CI/CD automation modules (run by workflows)
 │   ├── release.py       # Automated versioning, tagging, changelog
-│   ├── publish.py       # Build and publish to Gitea PyPI registry (--skip-build for non-Python repos)
+│   ├── publish.py       # Build, publish to Gitea PyPI registry, create Gitea release (with retry)
 │   ├── auto_merge.py    # Squash-merge PRs with task ID validation
 │   ├── check_auto_merge_ready.py  # Pre-merge validation gate (branch, PR title, Vikunja, behind-master)
 │   ├── _shared.py      # Shared utilities (get_latest_tag)
 │   ├── classify_changes.py  # User-facing vs infrastructure change detection
 │   ├── detect_release_commit.py  # Detect release commits on master
 │   ├── validate_commit_msg.py    # Conventional commit validation
-│   ├── pr_review.py     # Automated PR review + manual reviews (--event, --body, --checklist-confirmed)
 │   ├── post_merge.py    # Vikunja task updates after merge
 │   ├── sync_wiki.py     # Sync documentation to Gitea wiki
 │   ├── push_badges.py   # Generate and push quality badges (--retries for retry on git push failures)
@@ -90,7 +94,10 @@ src/devx/
 │   ├── doc_coverage.py  # Documentation coverage check
 │   ├── lint_docs.py  # Documentation linter (structure, links, headings, code blocks, orphans)
 │   ├── validate_deploy_ref.py  # Validate git tag for deployments (--github-output)
-│   └── record_deployed_tag.py  # Record deployed tag to Gitea repo variable
+│   ├── record_deployed_tag.py  # Record deployed tag to Gitea repo variable
+│   ├── cancel_superseded_runs.py  # Cancel in-flight CI runs for the same PR branch
+│   ├── check_workflow_artifact_deps.py  # Verify artifact download jobs depend on upload jobs
+│   └── check_workflow_tofu_init.py  # Verify tofu-state jobs have a tofu-init step
 ├── tools/               # Developer tooling modules (run locally or by CI)
 │   ├── setup.py         # Environment setup (venv, deps, hooks)
 │   ├── install_tools.py # Install actionlint, git-cliff, act_runner, tea, hadolint, vale
@@ -113,10 +120,17 @@ src/devx/
 │   ├── pr_logs.py           # Fetch logs for failed CI jobs
 │   ├── pr_label.py          # Add labels to PRs (idempotent)
 │   ├── pre_push_check.py    # Validate Vikunja task existence before push
+│   ├── check_docker_init.py  # Check Docker Compose services with healthchecks have init: true
+│   ├── check_ansible_set_fact_to_json.py  # Check set_fact tasks don't misuse to_json
+│   ├── check_alert_rules.py  # Validate Prometheus alert rules with promtool
+│   ├── check_ansible_no_log.py  # Check Ansible tasks for missing no_log on secrets
+│   ├── check_ansible_patterns.py  # Detect dangerous failure-masking patterns
+│   ├── check_jinja_expr.py  # Validate Jinja2 expressions in Ansible files
+│   ├── check_ansible_no_state_absent_on_db.py  # Prevent state:absent on DB paths
 │   └── _shared.py           # Shared tool utilities
 ├── opentofu.py          # OpenTofu output helpers (get_tofu_output, get_tofu_vm_ip, get_tofu_vm_field)
 ├── utils/               # Shared utilities (reusable across projects)
-│   ├── api.py            # API response helpers (is_truthy, is_falsy)
+│   ├── api.py            # API response helpers (is_truthy, is_falsy) + APIClient base class
 │   ├── ssh.py            # SSH exec + wait_for_ssh (pure-Python socket check)
 │   ├── crypto.py         # Secret generation (shell-safe passwords)
 │   ├── vault.py          # Ansible vault encrypt/decrypt helpers
@@ -124,12 +138,14 @@ src/devx/
 │   ├── confirm.py        # Typed confirmation validation for destructive ops
 │   ├── json_registry.py  # File-locked JSON registry for local state
 │   ├── step_tracker.py   # Multi-step operation tracking with reports
-│   └── logging.py        # XDG-compliant logging configuration
+│   ├── logging.py        # XDG-compliant logging configuration
+│   ├── ui.py             # say() — unified click.echo + logging output
+│   └── jinja.py          # Jinja2 environment helpers + Ansible-compatible filters
 └── molecule/            # Optional molecule testing helpers (for Ansible projects)
     ├── discover_runners.py    # Dynamic Gitea runner discovery
     ├── distribute_molecule.py # Distribute molecule scenarios across runners (LPT scheduling, --roles-root for multi-role)
-    ├── molecule_ci_guard.py   # Run molecule with cross-runner fail-fast (--roles-root)
     ├── molecule_all.py        # Run all molecule scenarios locally
+    ├── molecule_changed.py    # Detect which Ansible roles changed and output molecule scenarios
     ├── start_docker.py        # Ensure Docker daemon is running for molecule tests
     └── platforms.py           # Supported molecule platforms
 ```
@@ -141,8 +157,37 @@ src/devx/
 - **PYTHONPATH: src** — Workflows set `PYTHONPATH: src` (NOT `.:src` since there are no scripts at repo root)
 - **Config via env vars** — `DEVX_*` environment variables with `.env` file fallback
 
+
+## Spec-Driven Development
+
+Every change starts with a spec. No spec, no code.
+
+**Workflow:**
+1. Create Vikunja task → get `<PREFIX>-N` task ID
+2. Write spec at `docs/specs/<TASK-ID>.md` (see template in `.devin/skills/spec-driven-development/SKILL.md`)
+3. Create branch, implement with `# Implements: REQ-N` comments
+4. Tick all acceptance criteria checkboxes in spec
+5. Push and create PR — CI validates spec before expensive jobs
+
+**CI gates (pre-merge):**
+- `devx.ci.validate_spec` — checks spec exists, has required sections, REQ-IDs, all ACs checked
+- `devx.ci.check_pr_size` — max 500 lines / 10 files (excludes CHANGELOG, badges, locks)
+- `devx.ci.fast_molecule` — converge+verify only for changed roles, single platform
+
+**Nightly (infra only):**
+- Full molecule suite (all scenarios, all platforms) + staging deploy + integration tests
+- On failure: sets `NIGHTLY_STATUS=failed`, blocks staging deploys
+- Post-merge auto-deploy to staging checks this gate before deploying
+
+**Post-merge:**
+- Infra: auto-deploys to staging (if nightly gate is green)
+- GRM/sso-bridge: auto-publishes package, auto-creates infra dependency PR to bump pinned version
+
+**Skill:** `.devin/skills/spec-driven-development/SKILL.md` — full template and workflow details.
+
 ## PR Workflow (Mandatory)
 
+
 Every change to master goes through this workflow. No exceptions.
 
 ### Branch Protection (Required Gitea Settings)
@@ -193,7 +238,7 @@ docs: update README
 ### 6. Review the PR
 
 **Automated review (CI `validate` job):** Every PR triggers an automated
-review via `python -m devx.ci.pr_review` as a step in the `validate` job.
+review via the `pr-review` skill (agent-invoked, not a CI step).
 This posts a review with
 `COMMENT` (no issues) or `REQUEST_CHANGES` (issues found):
 
@@ -310,6 +355,20 @@ by `python -m devx.tools.install_tools` and configured by
 - `create_pr()` / `merge_pr()` / `review_pr()` — Pull request operations
 - `create_release()` / `list_releases()` — Release management
 
+**`devx.gitea_cli.configure_tea_login()`** — Configures tea login in
+containerized CI environments where `make setup` was not called. Used by
+`publish.py` (`--auto-login`) and `notify_failure.py` (`--auto-login`).
+Raises `TeaCLIError` if login configuration fails — this prevents cryptic
+"no available login" errors from subsequent tea commands.
+
+**Error handling**: `TeaCLI._run()` includes both stdout and stderr in
+`TeaCLIError` messages, because `tea` writes some errors (for example,
+"no available login") to stdout, not stderr.
+
+**Release creation retry**: `publish.py` retries Gitea release creation
+up to 3 times with exponential backoff (2s, 4s) on transient failures.
+"Already exists" errors are treated as success (idempotent).
+
 ### git-cliff Commit Preprocessing
 
 Merge commits on master have the format `DEVX-N: <conventional commit>`. The

CHANGELOG.md

@@ -2,6 +2,227 @@
 
 All notable changes to this project will be documented in this file.
 
+## [0.51.8] - 2026-08-26
+
+### Bug Fixes
+
+- Accept deps: as valid conventional commit type
+
+## [0.51.7] - 2026-08-26
+
+### Bug Fixes
+
+- Increase HTTP 500 retry count to 5 with longer backoff and visible logging
+
+## [0.51.6] - 2026-08-26
+
+### Bug Fixes
+
+- Use stderr=STDOUT to capture all docker push output in one stream
+
+## [0.51.5] - 2026-08-26
+
+### Bug Fixes
+
+- Check stdout for HTTP 500 in _run_push (docker sends to stdout)
+
+## [0.51.4] - 2026-08-26
+
+### Bug Fixes
+
+- Serialize registry uploads and retry on HTTP 500
+
+### Refactor
+
+- Remove cross-repo contract tests from devx
+
+## [0.51.3] - 2026-08-26
+
+### Bug Fixes
+
+- Fall back to CI bot token for auto-merge approval
+
+## [0.51.2] - 2026-08-26
+
+### Bug Fixes
+
+- Push-first strategy in build_image to avoid losing latest tag
+
+## [0.51.1] - 2026-08-25
+
+### Bug Fixes
+
+- Delete existing manifest before push (Gitea #31964 workaround)
+
+## [0.51.0] - 2026-08-25
+
+### Features
+
+- Add role defaults path to create_dependency_pr search
+
+## [0.50.2] - 2026-08-24
+
+### Bug Fixes
+
+- Update check_pr_size usage example with --repo and --pr-number args
+
+## [0.50.1] - 2026-08-15
+
+### Bug Fixes
+
+- Prefer rootless Docker socket over low-space inner DinD daemon
+- Check /run/host-docker.sock for host Docker daemon
+- Use /dev/shm/docker as data-root for inner dockerd
+- Kill existing dockerd before starting /dev/shm/docker daemon
+- Use /dev/shm/docker.sock socket for local dockerd
+- Add --iptables=false to local dockerd
+- Disable bridge and ip6tables for local dockerd
+- Use host Docker when root dir is inaccessible (free=0)
+- Prefer /run/host-docker.sock over inner dockerd
+- Start local dockerd instead of using low-space inner dockerd
+- Use container overlay for local dockerd data root
+- Kill inner dockerd with SIGKILL, use alt socket if alive
+- Kill dockerd by PID when pkill fails, use /dev/shm for alive daemon
+- Trust /var/run/docker.sock with free=0 when no inner dockerd exists
+
+## [0.50.0] - 2026-08-09
+
+### Features
+
+- Add 5 standalone lint scripts from infra
+
+## [0.49.0] - 2026-08-09
+
+### Features
+
+- Sync missing features from v0.49.x line to master
+
+## [0.48.2] - 2026-08-09
+
+### Bug Fixes
+
+- Remove dead translation keys and add missing one
+
+## [0.48.1] - 2026-08-08
+
+### Bug Fixes
+
+- *(setup)* Extract version from filename for mirror installs
+
+## [0.48.0] - 2026-08-08
+
+### Features
+
+- *(setup)* Mirror Ansible collections from Gitea registry with auth
+
+## [0.47.10] - 2026-08-05
+
+### Bug Fixes
+
+- Unique molecule container names per CI runner
+
+## [0.47.9] - 2026-08-03
+
+### Bug Fixes
+
+- Unique molecule container names per CI runner
+
+## [0.47.8] - 2026-08-03
+
+### Bug Fixes
+
+- Increase CI_SCALE_FACTOR default from 4 to 6
+
+## [0.47.7] - 2026-08-03
+
+### Bug Fixes
+
+- Scale check_test_speed limits on CI runners
+
+## [0.47.6] - 2026-08-03
+
+### Bug Fixes
+
+- Configure git auth in setup_image for git+https deps
+
+## [0.47.5] - 2026-08-03
+
+### Bug Fixes
+
+- Push wiki to main branch instead of master
+
+## [0.47.4] - 2026-08-03
+
+### Bug Fixes
+
+- Add User-Agent header to _download in install_tools
+
+## [0.47.3] - 2026-07-17
+
+### Bug Fixes
+
+- Bake promtool into ci-full image, add download timeout, speed up tests
+
+## [0.47.2] - 2026-07-17
+
+### Bug Fixes
+
+- Add retry logic to TeaCLI for transient HTTP errors (502/503/504/429)
+
+## [0.47.1] - 2026-07-16
+
+### Bug Fixes
+
+- Tea CLI login failure handling, error messages, release retry
+
+## [0.47.0] - 2026-07-14
+
+### Features
+
+- Add promtool to install_tools for alert rule validation
+
+## [0.46.0] - 2026-07-14
+
+### Features
+
+- Make check_test_isolation configurable via pyproject.toml
+
+## [0.45.1] - 2026-07-14
+
+### Bug Fixes
+
+- URL-encode package names and versions in clean_images API calls
+
+## [0.45.0] - 2026-07-14
+
+### Features
+
+- Add IO_INTERNAL_CALLS to check_test_isolation
+
+## [0.44.2] - 2026-07-14
+
+### Bug Fixes
+
+- Use legacy Docker builder to avoid Gitea registry 403
+
+## [0.44.1] - 2026-07-14
+
+### Bug Fixes
+
+- Disable Docker buildx provenance attestation
+
+## [0.44.0] - 2026-07-13
+
+### Features
+
+- Add fix_pr_title module and update_pr API method
+
+## [0.43.0] - 2026-07-13
+
+### Features
+
+- Add get_customer_vm_ip and get_observability_vm_ip to I/O check
+
 ## [0.42.0] - 2026-07-13
 
 ### Features

Makefile

@@ -1,4 +1,5 @@
 .PHONY: all setup setup-ci setup-quality setup-release setup-image install update lint lint-all lint-dockerfiles test test-unit pytest-cov clean install-tools install-hooks activate-scripts checkmake check-mutable-globals check-dep-docs check-test-speed build-images push-images build-images-dry-run clean-images
+.PHONY: check-workflow-artifact-deps check-workflow-tofu-init check-docker-init check-ansible-set-fact-to-json check-alert-rules
 
 PYTHON := python3
 VENV := .venv
@@ -65,7 +66,7 @@ setup-release: $(VENV)/bin/activate .env
 # an older devx.mak that doesn't yet define devx-setup-image. Consumer repos
 # (grm, infra) can safely alias to devx-setup-image since they install devx from PyPI.
 setup-image:
-	@if [ -d /opt/venv ]; then ln -sf /opt/venv $(VENV); . $(VENV)/bin/activate && pip install --no-cache-dir -e . 2>/dev/null; \
+	@if [ -d /opt/venv ]; then ln -sf /opt/venv $(VENV); . $(VENV)/bin/activate && pip install --no-cache-dir --no-deps -e . 2>/dev/null; \
 	else echo "[setup-image] /opt/venv not found — falling back to setup-ci"; $(MAKE) setup-ci; fi
 
 install-hooks:
@@ -113,6 +114,31 @@ pr-rebase: devx-pr-rebase
 lint-all: lint workflow-lint lint-dockerfiles
 	@echo "[lint-all] All linting checks passed."
 
+# ── Workflow / Ansible / Docker check tools ─────────────────────────────────
+# Generic check tools ported from infra. These targets are no-ops in devx
+# itself (no .gitea/workflows or ansible/ directory) but provide the
+# canonical entry points for consumer repos that include devx.mak.
+
+check-workflow-artifact-deps:
+	@$(BIN)/python -m devx.ci.check_workflow_artifact_deps || \
+		echo "[check-workflow-artifact-deps] No workflows directory found — skipping."
+
+check-workflow-tofu-init:
+	@$(BIN)/python -m devx.ci.check_workflow_tofu_init || \
+		echo "[check-workflow-tofu-init] No workflows directory found — skipping."
+
+check-docker-init:
+	@$(BIN)/python -m devx.tools.check_docker_init || \
+		echo "[check-docker-init] No ansible templates found — skipping."
+
+check-ansible-set-fact-to-json:
+	@$(BIN)/python -m devx.tools.check_ansible_set_fact_to_json || \
+		echo "[check-ansible-set-fact-to-json] No ansible directory found — skipping."
+
+check-alert-rules:
+	@$(BIN)/python -m devx.tools.check_alert_rules --template-path ansible/roles/observability/templates || \
+		echo "[check-alert-rules] No alert-rules template found — skipping."
+
 # Note: Not aliased to devx-lint-dockerfiles for the same reason as setup-image —
 # devx's own CI images may have an older devx.mak. Consumer repos can safely alias.
 lint-dockerfiles:

README.md

@@ -12,16 +12,16 @@ opinionated CI/CD pipeline: conventional commits, automated versioning via
 git-cliff, squash-merge automation, Vikunja task tracking, wiki sync, and
 quality badges.
 
-> An open-source project from **Oblachno** (облачно means *cloudy* in Bulgarian).
+> An open source project from **Oblachno** (облачно means *cloudy* in Bulgarian).
 
 [![CI](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/actions/workflows/ci.yml/badge.svg)](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/actions)
 [![License: GPL-3.0](https://img.shields.io/badge/license-GPL--3.0-blue)](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/src/branch/master/LICENSE)
-[![Coverage](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/raw/commit/ae591a0c94fab25fe52c7c7b251148fd3722764a/coverage.svg)](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/actions)
-[![Tests](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/raw/commit/ae591a0c94fab25fe52c7c7b251148fd3722764a/tests.svg)](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/actions)
-[![Docs](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/raw/commit/ae591a0c94fab25fe52c7c7b251148fd3722764a/docs.svg)](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/wiki)
-[![Code Quality](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/raw/commit/ae591a0c94fab25fe52c7c7b251148fd3722764a/quality.svg)](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/actions)
-[![Version](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/raw/commit/ae591a0c94fab25fe52c7c7b251148fd3722764a/version.svg)](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/releases)
-[![Python](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/raw/commit/ae591a0c94fab25fe52c7c7b251148fd3722764a/python.svg)](https://www.python.org/downloads/)
+[![Coverage](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/raw/commit/2f14bdfda981a35cc3af1a62855da16d9cdacdcf/coverage.svg)](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/actions)
+[![Tests](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/raw/commit/2f14bdfda981a35cc3af1a62855da16d9cdacdcf/tests.svg)](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/actions)
+[![Docs](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/raw/commit/2f14bdfda981a35cc3af1a62855da16d9cdacdcf/docs.svg)](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/wiki)
+[![Code Quality](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/raw/commit/2f14bdfda981a35cc3af1a62855da16d9cdacdcf/quality.svg)](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/actions)
+[![Version](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/raw/commit/2f14bdfda981a35cc3af1a62855da16d9cdacdcf/version.svg)](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/releases)
+[![Python](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/raw/commit/2f14bdfda981a35cc3af1a62855da16d9cdacdcf/python.svg)](https://www.python.org/downloads/)
 
 ## Why devx?
 
@@ -87,7 +87,7 @@ extra index and list devx in your dependencies:
 ```toml
 [project]
 dependencies = [
-    "devx>=0.42.0",
+    "devx>=0.51.8",
 ]
 
 [tool.pip]
@@ -101,8 +101,8 @@ pip install -e .
 ```
 
 > **Note:** If your project requires a specific devx version, pin it in
-> `dependencies` (for example, `"devx==0.42.0"`) or use a version constraint
-> (for example, `"devx>=0.42.0,<0.43"`).
+> `dependencies` (for example, `"devx==0.51.8"`) or use a version constraint
+> (for example, `"devx>=0.51.8,<0.52"`).
 
 ### Optional extras
 
@@ -226,10 +226,6 @@ python -m devx.molecule.distribute_molecule --runner-index 1 --max-runners 3
 python -m devx.molecule.distribute_molecule --list              # list all scenarios
 python -m devx.molecule.distribute_molecule --list-platforms    # list platforms
 
-# Run molecule tests with cross-runner fail-fast
-python -m devx.molecule.molecule_ci_guard pair1 pair2
-python -m devx.molecule.molecule_ci_guard --roles-root ansible/roles pair1 pair2
-
 # Run all molecule scenarios locally (sequential)
 python -m devx.molecule.molecule_all
 python -m devx.molecule.molecule_all --bin .venv/bin
@@ -303,7 +299,6 @@ devx --version
 | `devx molecule all` | Run all molecule scenarios on all supported platforms |
 | `devx molecule discover-runners` | Discover available Gitea Actions runners |
 | `devx molecule distribute` | Distribute molecule test pairs across parallel runners |
-| `devx molecule guard` | Run molecule tests with CI failure polling |
 
 See [CLI Commands](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/wiki/CLI-Commands)
 in the wiki for full command documentation with examples.

docker/ci-full/Dockerfile

@@ -20,5 +20,6 @@ COPY . /tmp/devx
 RUN pip install --no-cache-dir /tmp/devx[release,molecule,deploy] \
     && rm -rf /tmp/devx
 
-# Install git-cliff (changelog generator for release job) and OpenTofu (for infra deploy jobs)
-RUN python3 -m devx.tools.install_tools --tool git-cliff --tool tofu
+# Install git-cliff (changelog generator for release job), OpenTofu (for infra deploy jobs),
+# and promtool (Prometheus rule validator — used by every infra CI run for alert validation)
+RUN python3 -m devx.tools.install_tools --tool git-cliff --tool tofu --tool promtool

docs/decisions/0001-test-isolation-pytest-plugin-and-shift-left-quality-gates.md

@@ -40,20 +40,30 @@ invocation in any repo with devx installed automatically runs the
 static analysis. No extra Makefile target or CI step needed.
 
 The plugin (`devx.tools.check_test_isolation`) statically analyzes
-test files during `pytest_collection_finish` and emits
-`UserWarning` for violations:
+test files during `pytest_collection_finish` and **fails the test run**
+on any hard violation:
 
 - **unpatched-subprocess**: `subprocess.run/call/Popen/check_call/check_output`
-  called in a test function without `@patch`
+  called in a test function without `@patch` or `with patch(...)`
 - **unpatched-sleep**: `time.sleep` called without `@patch`
 - **unpatched-helper**: known subprocess-spawning helpers
   (`update_doc_versions`, `run_cmd`, `run_tests`) called without
   `@patch` (and without patching their internal dependencies)
 - **excessive-iterations**: `for _ in range(N)` where N > 100
+- **heavy-module-import**: `httpx`, `ansible`, etc. imported at module
+  level in test files, slowing collection for all tests
+- **reload-without-cleanup**: `importlib.reload()` called an odd number
+  of times, leaving module state modified
 
-The plugin recognizes transitive safety: if `run_cmd` is patched,
-`run_tests` (which calls `run_cmd`) is safe. This is tracked via
-`HELPER_INTERNAL_CALLS`.
+Transitive-subprocess findings (via call-graph analysis) are reported
+as **advisories** — the static analysis can't predict early exits or
+runtime branch conditions, so the runtime audit is authoritative.
+
+The plugin also wraps `subprocess.run` at runtime to catch real
+subprocess calls that leak through transitive call paths (for example
+`CliRunner.invoke(main)` → `main()` → `update_doc_versions()` →
+`subprocess.run()`). If a test spawns a real subprocess without
+`@patch`, the test fails.
 
 A standalone CLI (`python -m devx.tools.check_test_isolation`) is also
 provided for CI gates and pre-commit hooks where pytest isn't run.
@@ -85,16 +95,20 @@ is even created.
 
 - **Automatic enforcement**: The pytest plugin runs on every `pytest`
   invocation across devx, grm, and infra — no per-repo configuration
-  needed. New tests with unpatched subprocess calls emit warnings
-  immediately.
+  needed. New tests with unpatched subprocess calls fail immediately.
 - **Shift-left**: Translation gaps and test isolation violations are
   caught locally (pre-commit / `make lint`) instead of in CI.
-- **Fast feedback**: Static analysis adds <0.1s to test runs — no
-  runtime overhead.
-- **No false positives**: The transitive dependency tracking
-  (`HELPER_INTERNAL_CALLS`) correctly recognizes that patching
-  `run_cmd` makes `run_tests` safe, and patching `subprocess.run`
-  makes all helpers safe.
+- **Fast feedback**: Static analysis adds <0.1s to test runs; runtime
+  subprocess audit adds negligible overhead (wrapper checks a
+  thread-local flag).
+- **Transitive detection**: The call-graph BFS traces
+  `CliRunner.invoke(main)` → `main()` → `update_doc_versions()` →
+  `subprocess.run()`, catching indirect subprocess leaks that direct
+  analysis misses. The runtime audit provides authoritative enforcement.
+- **No false positives**: The call graph correctly recognizes that
+  patching `run_cmd` makes `run_tests` (which calls `run_cmd`) safe,
+  and class methods are excluded to avoid false positives when classes
+  like `TeaCLI` are patched.
 
 ### Negative
 
@@ -103,10 +117,12 @@ is even created.
   definitions) appears uncovered. Mitigated by `-p no:devx_test_isolation`
   in devx's own `pyproject.toml` `addopts` and `# pragma: no cover` on
   plugin hook functions.
-- **Static analysis limitations**: The plugin only sees direct calls
-  in test function bodies, not indirect calls through `main()` or
-  other wrappers. This is acceptable — the `check_test_speed` tool
-  catches the symptom (slow tests) for indirect cases.
+- **Static analysis limitations**: The call-graph BFS can't predict
+  runtime branch conditions or early exits — a test that patches
+  `shutil.which` to return `None` may skip the subprocess path
+  entirely, but the static analysis still reports it. Transitive
+  findings are advisories (exit 0) for this reason; the runtime audit
+  is authoritative.
 - **Translation burden**: Every new `_()` call in source requires
   adding 6 language translations. This is by design (all supported
   languages must be complete) but adds friction for quick prototypes.
@@ -122,21 +138,36 @@ in consumer repos.
 
 ### Disabling the Plugin
 
-- `--no-test-isolation` flag: disables analysis for a single run
+- `--no-test-isolation` flag: disables static analysis and runtime
+  subprocess audit for a single run
 - `-p no:devx_test_isolation` in `addopts`: disables for a repo
   (used in devx's own `pyproject.toml` for coverage reasons)
 
-### Strict Mode
+### Call-Graph Analysis
 
-- `--strict-test-isolation` flag: promotes warnings to errors and
-  prints a summary to stderr
-- `filterwarnings = ["error:Test isolation:UserWarning"]` in
-  `pyproject.toml`: same effect via pytest's warning filter system
+The `CallGraph` class parses all `.py` files under `src/` and builds
+a map of function → called functions. When a test calls
+`CliRunner.invoke(target)`, a BFS traces the call graph from `target`
+to find all reachable functions. Class methods are excluded from the
+call graph to avoid false positives when classes are patched (for example
+`@patch("...TeaCLI")` mocks all methods). The BFS respects `@patch`
+decorators — if a function is patched, traversal stops at that node.
+
+### Runtime Subprocess Audit
+
+The `_SubprocessAudit` singleton wraps `subprocess.run`, `call`,
+`check_call`, `check_output`, and `Popen` with thread-local
+recording wrappers. During each non-integration test, the wrapper
+records calls; if any are recorded (that is the test didn't `@patch`
+subprocess), the test fails. The wrappers check a thread-local flag,
+so inactive audits have zero overhead beyond the flag check.
 
 ### Known Subprocess Helpers
 
 The `KNOWN_SUBPROCESS_HELPERS` dict maps function names to
 descriptions. `HELPER_INTERNAL_CALLS` maps each helper to the
 function names it internally calls, enabling transitive safety
-checks. Both are defined in `check_test_isolation.py` and can be
-extended as new subprocess-spawning helpers are added to devx.
+checks for direct calls in test functions. The call-graph BFS
+handles transitive detection for `CliRunner.invoke` targets. Both
+are defined in `check_test_isolation.py` and can be extended as
+new subprocess-spawning helpers are added to devx.

docs/index.md

@@ -8,16 +8,16 @@ parallel test distribution, and more into a single installable package.
 It was extracted from the [GRM](https://git.oblachno.oblachno.fyi/oblachno-oss/grm)
 project to be reusable across all oblachno-oss repositories.
 
-> An open-source project from **Oblachno** (облачно means *cloudy* in Bulgarian).
+> An open source project from **Oblachno** (облачно means *cloudy* in Bulgarian).
 
 [![CI](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/actions/workflows/ci.yml/badge.svg)](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/actions)
 [![License: GPL-3.0](https://img.shields.io/badge/license-GPL--3.0-blue)](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/src/branch/master/LICENSE)
-[![Coverage](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/raw/commit/ae591a0c94fab25fe52c7c7b251148fd3722764a/coverage.svg)](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/actions)
-[![Tests](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/raw/commit/ae591a0c94fab25fe52c7c7b251148fd3722764a/tests.svg)](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/actions)
-[![Docs](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/raw/commit/ae591a0c94fab25fe52c7c7b251148fd3722764a/docs.svg)](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/wiki)
-[![Code Quality](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/raw/commit/ae591a0c94fab25fe52c7c7b251148fd3722764a/quality.svg)](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/actions)
-[![Version](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/raw/commit/ae591a0c94fab25fe52c7c7b251148fd3722764a/version.svg)](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/releases)
-[![Python](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/raw/commit/ae591a0c94fab25fe52c7c7b251148fd3722764a/python.svg)](https://www.python.org/downloads/)
+[![Coverage](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/raw/commit/2f14bdfda981a35cc3af1a62855da16d9cdacdcf/coverage.svg)](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/actions)
+[![Tests](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/raw/commit/2f14bdfda981a35cc3af1a62855da16d9cdacdcf/tests.svg)](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/actions)
+[![Docs](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/raw/commit/2f14bdfda981a35cc3af1a62855da16d9cdacdcf/docs.svg)](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/wiki)
+[![Code Quality](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/raw/commit/2f14bdfda981a35cc3af1a62855da16d9cdacdcf/quality.svg)](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/actions)
+[![Version](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/raw/commit/2f14bdfda981a35cc3af1a62855da16d9cdacdcf/version.svg)](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/releases)
+[![Python](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/raw/commit/2f14bdfda981a35cc3af1a62855da16d9cdacdcf/python.svg)](https://www.python.org/downloads/)
 
 ## Overview
 
@@ -74,14 +74,14 @@ Add devx to your `pyproject.toml` dependencies and configure the registry:
 ```toml
 [project]
 dependencies = [
-    "devx>=0.42.0",
+    "devx>=0.51.8",
 ]
 
 [tool.pip]
 extra-index-url = "https://git.oblachno.oblachno.fyi/api/packages/oblachno-oss/pypi/simple"
 ```
 
-Pin a specific version if needed: `"devx==0.42.0"` or `"devx>=0.42.0,<0.43"`.
+Pin a specific version if needed: `"devx==0.51.8"` or `"devx>=0.51.8,<0.52"`.
 
 ### Optional extras
 
@@ -104,8 +104,8 @@ devx is a self-contained Python package under `src/devx/`:
 - **Dev tools** (`devx.tools`) — setup, install_tools, check_test_speed,
   configure_repo, generate_badges, generate_cliff_config, install_checkmake
 - **Molecule tools** (`devx.molecule`) — Optional, for projects with Ansible
-  roles: distribute_molecule, molecule_ci_guard, molecule_all, discover_runners,
-  start_docker, platforms
+  roles: distribute_molecule, molecule_all, discover_runners, start_docker,
+  platforms
 
 See [Architecture](Architecture) for the full package structure, module
 descriptions, design principles, and data flow diagrams.
@@ -132,7 +132,7 @@ devx provides a `devx` CLI with three command groups:
 
 - `devx ci <command>` — CI/CD automation (17 commands)
 - `devx tools <command>` — Developer tools (9 commands)
-- `devx molecule <command>` — Molecule testing (4 commands, optional)
+- `devx molecule <command>` — Molecule testing (3 commands, optional)
 
 See [CLI Commands](CLI-Commands) for full command documentation with examples.
 

docs/retrospectives/2026-07-12-self-approval-fallback-and-ci-consolidation.md

@@ -132,7 +132,7 @@ unblocked auto-merge across all three repos.
 ### 2. Double-Prefix Detection (MEDIUM impact)
 
 `check_auto_merge_ready.py` now detects and rejects Vikunja task titles
-that include the identifier prefix (for example, "DEVX-127: Fix...").
+that include the identifier prefix (for example, "DEVX-127: Fix").
 The validator adds the prefix automatically, so a double prefix would
 fail validation.
 

docs/specs/DEVX-155.md

@@ -0,0 +1,46 @@
+# DEVX-155: Replace pr_review with spec-driven CI gates and pr-review skill
+
+## Problem
+The `devx.ci.pr_review` module was a monolithic automated PR review tool that
+ran in CI and posted COMMENT/REQUEST_CHANGES reviews. It duplicated logic now
+better handled by an agent-invoked skill, and it blocked the introduction of
+spec-driven development gates (validate_spec, check_pr_size) that should run
+before expensive CI jobs.
+
+## Approach
+Remove `pr_review` and replace it with lightweight, focused CI gates plus a
+new `pr-review` skill for deep agent-invoked reviews.
+
+REQ-1: Add `devx.ci.validate_spec` — validates spec file exists, has required sections, REQ-IDs, all ACs checked
+REQ-2: Add `devx.ci.check_pr_size` — enforces max 500 lines / 10 files (excludes CHANGELOG, badges, locks)
+REQ-3: Add `devx.ci.fast_molecule` — detects changed roles, outputs fast molecule commands (converge+verify, single platform)
+REQ-4: Add `devx.ci.nightly_gate` — checks/sets NIGHTLY_STATUS repo variable to block staging deploys on nightly failure
+REQ-5: Add `devx.ci.create_dependency_pr` — auto-creates infra PR to bump pinned package version after grm/sso-bridge release
+REQ-6: Remove `devx.ci.pr_review` module and `tests/unit/test_pr_review.py`
+REQ-7: Update CI workflows to replace pr_review steps with validate_spec + check_pr_size + curl-based APPROVE
+REQ-8: Add `spec-driven-development` and `pr-review` skills under `.devin/skills/`
+REQ-9: Update AGENTS.md and skill docs to document the new spec-driven workflow
+
+## Test Plan
+- Unit tests for each new module (test_validate_spec, test_check_pr_size, test_fast_molecule, test_nightly_gate, test_create_dependency_pr, test_spec_driven_workflows)
+- Remove test_pr_review.py and pr_review references from test_cli.py (pr_review.py deleted from source)
+- Verify CI workflow YAML passes actionlint
+
+## Deploy Plan
+- Merge to master via auto-merge workflow
+- devx post-merge publishes new version; downstream repos (grm, infra, sso-bridge) bump their devx pin
+
+## Rollback Plan
+- Revert the merge commit; downstream repos keep their current devx pin
+- pr_review.py can be restored from git history if needed
+
+## Acceptance Criteria
+- [x] REQ-1: `devx.ci.validate_spec` module exists with `--branch` and `--github-output` options
+- [x] REQ-2: `devx.ci.check_pr_size` module exists with `--base`, `--head`, `--github-output` options
+- [x] REQ-3: `devx.ci.fast_molecule` module exists and outputs changed roles + commands
+- [x] REQ-4: `devx.ci.nightly_gate` module exists with `--action check/set-passed/set-failed`
+- [x] REQ-5: `devx.ci.create_dependency_pr` module exists with `--repo`, `--package`, `--new-version` options
+- [x] REQ-6: The pr_review CI module and its test file are deleted from source tree
+- [x] REQ-7: CI workflow uses validate_spec + check_pr_size + curl APPROVE instead of pr_review
+- [x] REQ-8: `.devin/skills/spec-driven-development/SKILL.md` and `.devin/skills/pr-review/SKILL.md` exist
+- [x] REQ-9: AGENTS.md documents spec-driven development workflow and pr-review skill

docs/specs/DEVX-156.md

@@ -0,0 +1,34 @@
+# DEVX-156: Fix commit message format and release new CI modules
+
+## Problem
+The DEVX-155 merge commit on master has an invalid format
+('DEVX-155: Replace...' missing conventional commit type). This blocks
+the post-merge release workflow's `validate_commit_msg` step, preventing
+`validate_spec`, `check_pr_size`, `nightly_gate`, and `create_dependency_pr`
+from being published to the Gitea PyPI registry. All downstream repos
+(grm, infra, sso-bridge) are blocked — their CI fails with
+`No module named devx.ci.validate_spec`.
+
+## Approach
+Add a trivial user-facing change (version doc comment) with a proper
+conventional commit format to trigger the post-merge release workflow.
+The release will publish the new CI modules that DEVX-155 introduced.
+
+REQ-1: Add a user-facing change to src/devx/ to trigger release
+REQ-2: Ensure the commit message follows conventional format (type: description)
+
+## Test Plan
+- Verify post-merge workflow runs successfully after merge
+- Verify a new release tag is created (v0.51.0 or similar)
+- Verify devx.ci.validate_spec is importable from the published package
+
+## Deploy Plan
+- Merge to master via auto-merge workflow
+- Post-merge workflow auto-releases and publishes
+
+## Rollback Plan
+- Revert the merge commit if release fails
+
+## Acceptance Criteria
+- [x] REQ-1: A user-facing change is added to src/devx/
+- [x] REQ-2: Commit message follows conventional format

docs/specs/DEVX-157.md

@@ -0,0 +1,24 @@
+# DEVX-157: Add role defaults path to create_dependency_pr search
+
+## Problem
+`create_dependency_pr` only searches `pyproject.toml` and the infra images vars file for pinned versions. The sso-bridge role pins its version in its role defaults file via `sso_bridge_version`, which is not searched.
+
+## Approach
+Add the sso-bridge role defaults path to the search paths.
+
+REQ-1: Add ROLE_DEFAULTS_PATH constant pointing to the sso-bridge role defaults file
+REQ-2: Include ROLE_DEFAULTS_PATH in the search loop
+
+## Test Plan
+- Verify existing tests pass
+- Verify find_pinned_version finds sso_bridge_version in the defaults file
+
+## Deploy Plan
+- Merge to master, auto-release new devx version
+
+## Rollback Plan
+- Revert the merge commit
+
+## Acceptance Criteria
+- [x] REQ-1: ROLE_DEFAULTS_PATH constant added
+- [x] REQ-2: search loop includes ROLE_DEFAULTS_PATH

docs/specs/DEVX-158.md

@@ -0,0 +1,38 @@
+# DEVX-158: Fix build-images workflow: delete existing manifest before push
+
+## Problem
+Gitea 1.27 has a known bug (#31964) where pushing a Docker image tag that
+already exists in the container registry fails with HTTP 500 "package
+version already exists." The build-images workflow has been failing for weeks because
+every push to `ci-base:latest`, `ci-quality:latest`, and `ci-full:latest`
+hits this error.
+
+## Approach
+Add a `delete_remote_manifest` function that deletes the existing manifest
+via the Docker registry v2 API before pushing. This works around the Gitea
+bug by ensuring the tag doesn't exist when the push starts.
+
+REQ-1: Add `delete_remote_manifest` function using Docker registry v2 API
+REQ-2: Call `delete_remote_manifest` before each `docker push` in `push_image`
+REQ-3: Pass registry credentials from `main` to `push_image`
+REQ-4: Handle errors gracefully — never block the push if delete fails
+REQ-5: 100% test coverage for new code
+
+## Test Plan
+- Unit tests for `delete_remote_manifest` (success, 404, 500, network error)
+- Unit tests for `push_image` with and without credentials
+- Verify existing tests still pass
+
+## Deploy Plan
+- Merge to master, auto-release new devx version
+- The build-images workflow will use the new code on the next run
+
+## Rollback Plan
+- Revert the merge commit
+
+## Acceptance Criteria
+- [x] REQ-1: `delete_remote_manifest` function added
+- [x] REQ-2: Called before each push in `push_image`
+- [x] REQ-3: Credentials passed from `main` to `push_image`
+- [x] REQ-4: Errors don't block the push (returns True on failure)
+- [x] REQ-5: 100% test coverage

docs/specs/DEVX-159.md

@@ -0,0 +1,41 @@
+# DEVX-159: Fix build_image push-first strategy to avoid losing latest tag
+
+## Problem
+The `push_image` function in `build_image.py` deletes the existing
+manifest *before* pushing (Gitea #31964 workaround). When the push
+fails for other reasons (HTTP 500), the old tag is lost, breaking all
+CI jobs that use that image.
+
+This caused `ci-base:latest` to disappear from the registry when
+build-images run #4104 failed with HTTP 500 on push, after already
+deleting the old `latest` manifest.
+
+## Approach
+Switch to a push-first strategy:
+1. Try pushing directly
+2. Only if push fails with "already exists" (Gitea #31964), delete
+   the old manifest and retry
+3. If push fails for any other reason, the old manifest is preserved
+
+REQ-1: Push first, no pre-emptive delete
+REQ-2: Delete + retry only on "already exists" error
+REQ-3: Old manifest preserved on non-already-exists failures
+REQ-4: 100% test coverage of new logic
+
+## Test Plan
+- Unit tests for all push paths (success, already-exists retry,
+  non-already-exists failure, retry-also-fails)
+- Verify existing tests still pass
+
+## Deploy Plan
+- Merge to master, build-images workflow uses new push logic on next
+  image rebuild
+
+## Rollback Plan
+- Revert the merge commit
+
+## Acceptance Criteria
+- [x] REQ-1: Push first, no pre-emptive delete
+- [x] REQ-2: Delete + retry only on "already exists" error
+- [x] REQ-3: Old manifest preserved on non-already-exists failures
+- [x] REQ-4: 100% test coverage of new logic

docs/specs/DEVX-160.md

@@ -0,0 +1,31 @@
+# DEVX-160: Remove cross-repo contract tests from devx
+
+## Problem
+devx unit tests (`test_spec_driven_workflows.py`) were validating workflow
+YAML and skill files in infra, grm, sso-bridge, and Mattermost OIDC repos.
+This is an architecture violation — devx must not be aware of other repos.
+Those repos consume devx; devx does not test them.
+
+## Approach
+Rewrite `test_spec_driven_workflows.py` to only test devx's own workflows
+and skills. Remove all references to `_OBLACHNO_ROOT`, `_INFRA`, `_GRM`,
+`_SSO_BRIDGE`, and parametrized repo lists.
+
+REQ-1: No references to other repos in devx tests
+REQ-2: All devx workflow/skill tests still pass
+REQ-3: 100% coverage maintained
+
+## Test Plan
+- Run `pytest tests/unit/test_spec_driven_workflows.py` — all pass
+- Run full test suite with coverage — 100%
+
+## Deploy Plan
+- Merge to master
+
+## Rollback Plan
+- Revert the merge commit
+
+## Acceptance Criteria
+- [x] REQ-1: No references to other repos in devx tests
+- [x] REQ-2: All devx workflow/skill tests still pass
+- [x] REQ-3: 100% coverage maintained

docs/specs/DEVX-161.md

@@ -0,0 +1,27 @@
+# DEVX-161: Fix auto-merge self-approval: use CI bot token fallback
+
+## Problem
+The auto-merge workflow posts an APPROVE review using
+`REVIEWER_GITEA_API_TOKEN`. When this token belongs to the same user
+who created the PR, Gitea rejects the self-approval, causing the merge
+to fail with HTTP 405 "Does not have enough approvals."
+
+## Approach
+Try `REVIEWER_GITEA_API_TOKEN` first; if it fails (self-approval
+rejection), fall back to `CI_GITEA_API_TOKEN` (kireto — CI bot account).
+
+REQ-1: Auto-merge posts approval with fallback to CI bot token
+REQ-2: Approval step reports which token succeeded
+
+## Test Plan
+- Create a PR and observe auto-merge succeeds
+
+## Deploy Plan
+- Merge to master
+
+## Rollback Plan
+- Revert the merge commit
+
+## Acceptance Criteria
+- [x] REQ-1: Auto-merge posts approval with fallback to CI bot token
+- [x] REQ-2: Approval step reports which token succeeded

docs/specs/DEVX-162.md

@@ -0,0 +1,41 @@
+# DEVX-162: Fix registry push race condition: serialize uploads + retry on HTTP 500
+
+## Problem
+The Gitea container registry (v1.27.2) has a known race condition in
+`BlobUploader.Append()` where concurrent blob uploads cause the file
+offset and DB model to get out of sync, producing HTTP 500 "offset
+mismatch between file and model" errors. This causes the build-images
+workflow to fail intermittently when pushing runner images.
+
+The `package_blob_upload` table accumulates stale entries from failed
+uploads that worsen the problem over time.
+
+## Approach
+Two fixes in devx (a third fix — scheduled cleanup — is tracked
+separately as OBL-INFRA-537):
+
+1. Set `DOCKER_MAX_CONCURRENT_UPLOADS=1` in the build-images workflow
+   to serialize blob uploads and avoid the race condition.
+
+2. Add HTTP 500 retry logic to `push_image` in `build_image.py`.
+   When a push fails with HTTP 500 (not "already exists"), retry up
+   to 3 times with exponential backoff (5s, 10s, 20s).
+
+REQ-1: Build-images workflow sets DOCKER_MAX_CONCURRENT_UPLOADS=1
+REQ-2: push_image retries on HTTP 500 with exponential backoff
+REQ-3: All existing tests pass with 100% coverage
+
+## Test Plan
+- Unit tests for retry logic (mock subprocess)
+- Manual: trigger build-images workflow and verify push succeeds
+
+## Deploy Plan
+- Merge to master
+
+## Rollback Plan
+- Revert the merge commit
+
+## Acceptance Criteria
+- [x] REQ-1: Build-images workflow sets DOCKER_MAX_CONCURRENT_UPLOADS=1
+- [x] REQ-2: push_image retries on HTTP 500 with exponential backoff
+- [x] REQ-3: All existing tests pass with 100% coverage

docs/specs/DEVX-163.md

@@ -0,0 +1,33 @@
+# DEVX-163: Fix _run_push to check stdout for HTTP 500
+
+## Problem
+`_run_push` only checked `result.stderr` for HTTP 500, but docker push
+sends the "received unexpected HTTP status: 500 Internal Server Error"
+message to **stdout**, not stderr. This means the tenacity retry logic
+added in DEVX-162 never triggered — the push failed immediately without
+retrying.
+
+## Approach
+Check both `result.stdout` and `result.stderr` for the "500" status code.
+Also update the "already exists" check in `push_image` to check both
+streams, since docker may send that message to stdout as well.
+
+REQ-1: _run_push checks both stdout and stderr for HTTP 500
+REQ-2: push_image "already exists" check uses combined stdout+stderr
+REQ-3: All existing tests pass with 100% coverage
+
+## Test Plan
+- Unit tests for stdout 500 detection
+- Unit tests for stderr 500 detection
+- Manual: trigger build-images workflow and verify retry works
+
+## Deploy Plan
+- Merge to master
+
+## Rollback Plan
+- Revert the merge commit
+
+## Acceptance Criteria
+- [x] REQ-1: _run_push checks both stdout and stderr for HTTP 500
+- [x] REQ-2: push_image "already exists" check uses combined stdout+stderr
+- [x] REQ-3: All existing tests pass with 100% coverage

docs/specs/DEVX-164.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-165.md

@@ -0,0 +1,31 @@
+# DEVX-165: Accept deps: as valid conventional commit type
+
+## Problem
+The commit validator rejects `deps:` as a conventional commit type, causing
+post-merge CI failures on grm and sso-bridge repos where automated dependency
+bump PRs use `deps: bump devx...` as the commit message.
+
+## Approach
+REQ-1: Add `deps` to `CONVENTIONAL_RE` in `src/devx/config.py`
+REQ-2: Update the allowed types list in the error message in
+  `src/devx/ci/validate_commit_msg.py`
+REQ-3: Add test coverage for `deps:` type in `tests/unit/test_config.py`
+  and `tests/unit/test_validate_commit_msg.py`
+
+## Test Plan
+- `make pytest-cov` passes with 100% coverage
+- `make lint-all` passes
+
+## Deploy Plan
+- Merge to master → post-merge auto-publishes new devx version
+- grm and sso-bridge bump devx version to pick up the fix
+
+## Rollback Plan
+- Revert the merge commit
+
+## Acceptance Criteria
+- [x] REQ-1: Add `deps` to `CONVENTIONAL_RE` in `src/devx/config.py`
+- [x] REQ-2: Update the allowed types list in the error message in
+  `src/devx/ci/validate_commit_msg.py`
+- [x] REQ-3: Add test coverage for `deps:` type in `tests/unit/test_config.py`
+  and `tests/unit/test_validate_commit_msg.py`

docs/tech/architecture.md

@@ -50,7 +50,6 @@ src/devx/
     ├── __init__.py
     ├── discover_runners.py      # Dynamic Gitea runner discovery
     ├── distribute_molecule.py   # Distribute scenarios across runners
-    ├── molecule_ci_guard.py     # Run molecule with cross-runner fail-fast
     ├── molecule_all.py          # Run all molecule scenarios locally
     ├── start_docker.py          # Ensure Docker is available for molecule
     └── platforms.py             # Supported molecule platforms
@@ -87,11 +86,11 @@ overridden via environment variables with the `DEVX_` prefix. Provides:
 
 - `GITEA_API_URL` / `VIKUNJA_API_URL` — API endpoints
 - `REPO_OWNER` — repository owner (must be set per-project)
-- `TASK_PREFIX` / `TASK_ID_RE` — task ID prefix and regex (for example, `DEVX-N`)
+- `TASK_PREFIX` / `TASK_ID_RE` — task ID prefix and regular expression (for example, `DEVX-N`)
 - `VIKUNJA_PROJECT_ID` — Vikunja project for task tracking
 - `DEFAULT_TIMEOUT`, `DEFAULT_PER_PAGE` — HTTP client defaults
 - `MAX_RETRIES`, `RETRY_BACKOFF_BASE`, `RETRY_STATUS_CODES` — retry config
-- `CONVENTIONAL_RE` — conventional commit format regex
+- `CONVENTIONAL_RE` — conventional commit format regular expression
 
 ### `exceptions.py`
 
@@ -109,7 +108,7 @@ wraps user-facing strings for translation.
 
 Projects can extend translations by setting `DEVX_TRANSLATIONS_PATH` to a
 custom JSON file. Keys from the project's file are merged on top of devx's
-built-in translations, allowing projects to override or add keys without
+built-in translations, allowing projects to override, or add keys without
 modifying the package.
 
 ### `api_clients.py`
@@ -171,7 +170,7 @@ from `devx.api_clients`, `devx.config`, `devx.gitea_cli`, and `devx.i18n`.
 
 Automated release using git-cliff. Calculates the next semver version from
 conventional commits since the last tag, updates `__version__` in
-`__init__.py` and `CHANGELOG.md`, runs lint and tests to verify the release
+`__init__.py` and `CHANGELOG.md`, runs lint, and tests to verify the release
 is healthy, commits with `release: vX.Y.Z [skip ci]`, creates an annotated
 tag, and pushes both to master.
 
@@ -288,7 +287,7 @@ Click commands from `cli.py` and verifies each has documentation in
 ### `discover_runners.py`
 
 Discovers available Gitea Actions runners at three levels: repository,
-organization, and instance (admin). Falls back to the `MOLECULE_RUNNERS` repo
+organization, and instance (administrator). Falls back to the `MOLECULE_RUNNERS` repo
 variable or `DEFAULT_MAX_RUNNERS` (3). Outputs runner count or a JSON index
 array for use as a dynamic matrix in Gitea Actions.
 
@@ -300,9 +299,9 @@ Distributes files matching a glob pattern across N parallel runners
 
 ### `integration_guard.py`
 
-Runs pytest with the same cross-runner failure detection mechanism used by
-`molecule_ci_guard`. If any other integration-tests matrix runner reports
-failure, the current pytest subprocess is killed and this runner exits early.
+Runs pytest with cross-runner failure detection. A background thread polls
+the Gitea API. If any other integration-tests matrix runner reports failure,
+the current pytest subprocess is killed and this runner exits early.
 
 ## Developer tools (`devx.tools`)
 
@@ -330,7 +329,7 @@ Supports `--tool` to install specific tools and `--list` to show status.
 Runs unit tests and enforces execution-time budgets. Two quality gates:
 total suite time must not exceed `--max-seconds` (default: 10s), and no
 individual test may exceed `--max-single-seconds` (default: 0.5s, 0 to
-disable). Runs `make test-unit` with `PYTEST_ADDOPTS=--durations=0`.
+off). Runs `make test-unit` with `PYTEST_ADDOPTS=--durations=0`.
 
 ### `check_test_isolation.py`
 
@@ -382,13 +381,6 @@ the supported OS platform matrix. Supports `--roles-root` for multi-role
 repositories, `--list` to list scenarios, and `--list-platforms` to list
 platforms.
 
-### `molecule_ci_guard.py`
-
-Runs molecule tests sequentially while polling the Gitea API for other runner
-failures. If any other molecule matrix runner reports failure, the current
-molecule subprocess is killed and this runner exits early. Supports both
-single-role (4-part) and multi-role (5-part) pair encoding.
-
 ### `molecule_all.py`
 
 Runs all molecule scenarios on all supported OS platforms sequentially.

docs/tech/ci-cd-workflow.md

@@ -478,15 +478,6 @@ python -m devx.molecule.distribute_molecule --list
 python -m devx.molecule.distribute_molecule --list-platforms
 ```
 
-### `molecule_ci_guard.py`
-
-Runs molecule tests sequentially while polling the Gitea API for other runner
-failures. Aborts early if another runner fails the same job.
-
-```bash
-python -m devx.molecule.molecule_ci_guard [--roles-root <dir>] pair1 pair2 ...
-```
-
 ### `validate_commit_msg.py`
 
 Validates commit messages. On feature branches: conventional commits only

docs/user/cli-commands.md

@@ -85,7 +85,7 @@ devx ci detect-release-commit
 
 Discover available Gitea Actions runners for dynamic job distribution.
 Queries the Gitea API for registered runners at repository, organization, and
-instance (admin) levels. Falls back to `MOLECULE_RUNNERS` repo variable or
+instance (administrator) levels. Falls back to `MOLECULE_RUNNERS` repo variable or
 `DEFAULT_MAX_RUNNERS` (3).
 
 ```bash
@@ -315,6 +315,56 @@ devx ci validate-commit-msg commit-msg.txt --branch master
 Options:
 - `--branch <branch>` — override branch detection (for CI use)
 
+### `devx ci cancel-superseded-runs`
+
+Cancel in-flight CI runs for the same PR branch when a new push triggers
+a new run. Uses the Gitea Actions API to list running pull_request runs
+and cancel those with a lower run ID on the same branch.
+
+```bash
+devx ci cancel-superseded-runs \
+    --repo "$REPOSITORY" \
+    --current-run-id "$GITHUB_RUN_ID" \
+    --head-branch "$HEAD_REF"
+```
+
+Options:
+- `--repo <owner/repo>` — repository (required)
+- `--current-run-id <id>` — current run ID, not cancelled (required)
+- `--head-branch <branch>` — PR head branch name (required)
+- `--dry-run` — list superseded runs without cancelling
+- `--base-url <url>` — Gitea base URL (default: `GITEA_API_URL` env var)
+
+### `devx ci check-workflow-artifact-deps`
+
+Verify that workflow jobs downloading artifacts depend on the uploading
+job. Prevents the class of bug where a download job runs in parallel
+with the upload job and fails because the artifact isn't available yet.
+
+```bash
+devx ci check-workflow-artifact-deps
+devx ci check-workflow-artifact-deps --workflow .gitea/workflows/ci.yml
+```
+
+Options:
+- `--workflow <path>` — check a specific workflow file
+- `--workflows-dir <path>` — override workflows directory
+
+### `devx ci check-workflow-tofu-init`
+
+Verify that workflow jobs using tofu state (tofu output/plan/apply or
+scripts that call them) have a tofu-init step in the same job.
+
+```bash
+devx ci check-workflow-tofu-init
+devx ci check-workflow-tofu-init --workflow .gitea/workflows/deploy.yml
+```
+
+Options:
+- `--workflow <path>` — check a specific workflow file
+- `--workflows-dir <path>` — override workflows directory
+- `--state-script <name>` — add a script that uses tofu state (repeatable)
+
 ## Tools Commands
 
 ### `devx tools check-test-speed`
@@ -323,7 +373,7 @@ Run unit tests and enforce execution-time budgets. Two quality gates:
 
 - **Total suite time** must not exceed `--max-seconds` (default: 10s)
 - **Per-test time** — no individual test may exceed `--max-single-seconds`
-  (default: 0.5s, 0 to disable)
+  (default: 0.5s, 0 to turn off)
 
 Runs `make test-unit` with `PYTEST_ADDOPTS=--durations=0` so pytest emits
 per-test timing lines.
@@ -339,28 +389,37 @@ devx tools check-test-speed --max-seconds 4 --max-single-seconds 0.5
 Statically analyze test files for un-hermetic patterns that cause slow
 or flaky tests. Also available as a **pytest plugin** (auto-discovered
 via the `pytest11` entry point when devx is installed — runs
-automatically on every `pytest` invocation).
+automatically on every `pytest` invocation and **fails on violations**).
 
-Detected patterns:
+Detected patterns (hard errors — exit non-zero):
 
 - **unpatched-subprocess**: `subprocess.run/call/Popen/check_call/check_output`
-  called in a test function without `@patch`
+  called in a test function without `@patch` or `with patch(...)`
 - **unpatched-sleep**: `time.sleep` called without `@patch`
 - **unpatched-helper**: known subprocess-spawning helpers (`update_doc_versions`,
   `run_cmd`, `run_tests`) called without `@patch` or patching their internal deps
 - **excessive-iterations**: `for _ in range(N)` where N > 100
+- **heavy-module-import**: `httpx`, `ansible`, etc. imported at module level
+- **reload-without-cleanup**: `importlib.reload()` called an odd number of times
+
+Advisory patterns (exit 0 — runtime audit is authoritative):
+
+- **transitive-subprocess**: `CliRunner.invoke(target)` where `target`
+  transitively calls `subprocess.run` without being patched. Detected via
+  static call-graph analysis. The runtime subprocess audit catches actual
+  leaks — if a real subprocess runs without `@patch`, the test fails.
 
 ```bash
 devx tools check-test-isolation
-devx tools check-test-isolation --test-path tests/ --strict
-devx tools check-test-isolation --categories unpatched-subprocess,unpatched-sleep
+devx tools check-test-isolation --test-path tests/
+devx tools check-test-isolation --categories unpatched-subprocess,transitive-subprocess
 devx tools check-test-isolation --max-loop-iterations 50
+devx tools check-test-isolation --src-dir src/
 ```
 
 Pytest plugin options (automatic when devx is installed):
 
-- `--strict-test-isolation` — fail the test run on violations
-- `--no-test-isolation` — disable analysis for this run
+- `--no-test-isolation` — turn off static analysis and runtime subprocess audit
 - `--test-isolation-max-loop N` — max iterations per loop (default: 100)
 
 ### `devx tools configure-repo`
@@ -405,7 +464,7 @@ devx tools generate-cliff-config --prefix GRM --force  # overwrite existing
 Options:
 - `--prefix <prefix>` — task ID prefix (default: `DEVX_TASK_PREFIX` env var
   or `DEVX`)
-- `--output <file>` — output file path (default: `cliff.toml`)
+- `--output <file>` — output path (default: `cliff.toml`)
 - `--force` — overwrite existing file
 
 ### `devx tools install-checkmake`
@@ -479,6 +538,56 @@ devx tools pr-rebase                       # auto-detect PR from current branch
 Options (pass after `--`):
 - `--pr <N>` — PR number (auto-detected from current branch if omitted)
 
+### `devx tools check-docker-init`
+
+Check that Docker Compose services with healthchecks have `init: true`.
+Without `init: true`, CMD-SHELL healthchecks spawn child processes that
+become zombies when PID 1 doesn't reap them.
+
+```bash
+devx tools check-docker-init
+devx tools check-docker-init --path path/to/docker-compose.yml.j2
+```
+
+Options:
+- `--path <path>` — check a specific file or directory
+- `--templates-dir <path>` — override templates directory (default: `ansible/roles/`)
+
+### `devx tools check-ansible-set-fact-to-json`
+
+Check that Ansible `set_fact` tasks don't misuse `| to_json`. Using
+`to_json` in `set_fact` converts native Python types to JSON strings,
+causing iteration bugs (for example, iterating over characters instead
+of list items).
+
+```bash
+devx tools check-ansible-set-fact-to-json
+devx tools check-ansible-set-fact-to-json --path path/to/playbook.yml
+```
+
+Options:
+- `--path <path>` — check a specific file or directory
+- `--ansible-dir <path>` — override ansible directories (repeatable)
+
+### `devx tools check-alert-rules`
+
+Validate rendered Prometheus alert rules with `promtool check rules`.
+Renders a Jinja2 template with test values and validates the output.
+Skips (exits 0) if promtool is not on PATH.
+
+```bash
+devx tools check-alert-rules \
+    --template-path ansible/roles/observability/templates
+devx tools check-alert-rules \
+    --template-path ansible/roles/observability/templates \
+    --var grafana_base_url=https://grafana.example.com
+```
+
+Options:
+- `--template-path <path>` — path to templates directory (required)
+- `--template-name <name>` — template filename (default: `alert-rules.yml.j2`)
+- `--var key=value` — template variables (repeatable)
+
 ## Molecule Commands
 
 Molecule commands require the `molecule` extra (`pip install devx[molecule]`).
@@ -522,29 +631,3 @@ Options:
 - `--list-platforms` — list all platforms, one per line
 - `--roles-root <dir>` — roles root directory for multi-role repos (default:
   `ansible/roles`)
-
-### `devx molecule guard`
-
-Run molecule tests sequentially with CI failure polling. A background thread
-polls the Gitea API. If any other molecule matrix runner reports failure, the
-current molecule subprocess is killed and this runner exits early with code 1.
-
-```bash
-devx molecule guard pair1 pair2 pair3
-devx molecule guard --roles-root ansible/roles pair1 pair2
-```
-
-Each pair is encoded as:
-- **Single-role (4-part):** `scenario|platform_name|platform_image|platform_command`
-- **Multi-role (5-part):** `role|scenario|platform_name|platform_image|platform_command`
-
-Options:
-- `--roles-root <dir>` — roles root directory for multi-role repos
-
-Environment variables:
-- `GITEA_URL` — base URL of the Gitea instance
-- `CI_GITEA_TOKEN` — API token with repo access
-- `RUN_ID` — workflow run ID (`GITHUB_RUN_ID`)
-- `JOB_NAME` — base job name (`GITHUB_JOB`)
-- `MATRIX_INDEX` — current matrix index (runner-index)
-- `GITEA_REPOSITORY` — repository in `owner/repo` format

docs/user/getting-started.md

@@ -48,12 +48,12 @@ Add devx to your `pyproject.toml`:
 ```toml
 [project]
 dependencies = [
-    "devx>=0.42.0",
+    "devx>=0.51.8",
 ]
 
 [project.optional-dependencies]
 dev = [
-    "devx>=0.42.0",
+    "devx>=0.51.8",
 ]
 ```
 

pyproject.toml

@@ -20,6 +20,8 @@ dependencies = [
     "python-dotenv==1.2.2",
     "click==8.4.2",
     "tenacity==9.1.4",  # retry logic for GiteaClient/VikunjaClient
+    "jinja2==3.1.6",  # template rendering (devx.utils.jinja, check_alert_rules)
+    "pyyaml==6.0.3",  # YAML parsing (workflow checks, ansible checks)
 ]
 
 [project.scripts]
@@ -62,13 +64,16 @@ molecule = [
     "ansible-core==2.21.1",
 ]
 # Deploy tools (for infra staging/production deployments)
+# Versions aligned with infra's pyproject.toml to avoid reinstalls on every CI job.
+# bcrypt and PyJWT are infra deps not in devx core — included here so the CI
+# image has them and setup-image can use --no-deps (skip dep resolution).
 deploy = [
     "ansible-core==2.21.1",
-    "boto3==1.43.37",
+    "boto3==1.43.44",
     "docker==7.1.0",
-    "jinja2==3.1.6",
-    "pyyaml==6.0.3",
-    "cryptography==49.0.0",
+    "cryptography==50.0.0",
+    "bcrypt==5.0.0",
+    "PyJWT==2.13.0",
 ]
 # Full dev environment (local development)
 dev = [

src/devx/__init__.py

@@ -1,3 +1,9 @@
-"""devx — reusable development and CI/CD tools for oblachno-oss projects."""
+"""devx — reusable development and CI/CD tools for oblachno-oss projects.
 
-__version__ = "0.42.0"
+Provides CI/CD automation (validate_spec, check_pr_size, nightly_gate,
+create_dependency_pr, auto_merge, release, publish), developer tooling
+(setup, install_tools, configure_repo, create_task, create_pr), and
+molecule testing helpers for Ansible projects.
+"""
+
+__version__ = "0.51.8"

src/devx/api_clients.py

@@ -224,6 +224,16 @@ class GiteaClient:
         r = self._request("GET", f"/pulls/{pr_number}")
         return r.json()
 
+    def update_pr(self, pr_number: str | int, fields: dict[str, Any]) -> dict[str, Any]:
+        """Update a pull request (e.g. title, body, state).
+
+        Args:
+            pr_number: PR number.
+            fields: Dict of fields to update (e.g. {"title": "new title"}).
+        """
+        r = self._request("PATCH", f"/pulls/{pr_number}", json=fields)
+        return r.json()
+
     def create_pr(self, title: str, head: str, base: str = "master", body: str = "") -> dict[str, Any]:
         """Create a pull request and return the PR dict.
 

src/devx/ci/cancel_superseded_runs.py

@@ -0,0 +1,185 @@
+"""Cancel superseded CI runs for the same PR.
+
+When a new push to a PR branch triggers a new CI run, any in-flight
+runs for the same PR are wasting runner time. This script cancels
+all but the latest running CI run for each PR branch.
+
+Uses the Gitea Actions API:
+  GET  /repos/{owner}/{repo}/actions/runs?status=in_progress&event=pull_request
+  POST /repos/{owner}/{repo}/actions/runs/{run_id}/cancel
+
+Usage::
+
+  # CI (cancels superseded runs for the current PR):
+  python -m devx.ci.cancel_superseded_runs \\
+      --repo "$REPOSITORY" \\
+      --current-run-id "$GITHUB_RUN_ID" \\
+      --head-branch "$HEAD_REF"
+
+  # Dry-run (lists what would be cancelled without cancelling):
+  python -m devx.ci.cancel_superseded_runs \\
+      --repo "$REPOSITORY" \\
+      --current-run-id "$GITHUB_RUN_ID" \\
+      --head-branch "$HEAD_REF" \\
+      --dry-run
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+import urllib.error
+import urllib.request
+
+_HTTP_NO_CONTENT = 204
+_HTTP_NOT_FOUND = 404
+_HTTP_BAD_REQUEST = 400
+_PAGE_SIZE = 50
+
+
+def _log(msg: str) -> None:
+    """Log to stderr."""
+    print(f"[cancel-superseded] {msg}", file=sys.stderr, flush=True)
+
+
+def _api_request(
+    method: str,
+    path: str,
+    token: str,
+    base_url: str,
+    body: dict | None = None,
+) -> dict | list:
+    """Make a Gitea API request."""
+    url = f"{base_url}/api/v1{path}"
+    headers = {
+        "Authorization": f"token {token}",
+        "Content-Type": "application/json",
+        "Accept": "application/json",
+    }
+    data = json.dumps(body).encode() if body else None
+    req = urllib.request.Request(url, data=data, headers=headers, method=method)
+    try:
+        with urllib.request.urlopen(req, timeout=30) as resp:  # nosec B310 — authenticated API request to known Gitea instance
+            if resp.status == _HTTP_NO_CONTENT:
+                return {}
+            return json.loads(resp.read().decode())
+    except urllib.error.HTTPError as e:
+        _log(f"API error {e.code} on {method} {path}: {e.read().decode()[:200]}")
+        raise
+    except urllib.error.URLError as e:
+        _log(f"URL error on {method} {path}: {e}")
+        raise
+
+
+def list_running_runs(repo: str, token: str, base_url: str) -> list[dict]:
+    """List all running CI runs for pull_request events."""
+    runs: list[dict] = []
+    page = 1
+    while True:
+        result = _api_request(
+            "GET",
+            f"/repos/{repo}/actions/runs?status=in_progress&event=pull_request&page={page}&limit=50",
+            token,
+            base_url,
+        )
+        # Gitea returns {"workflow_runs": [...], "total_count": N}
+        page_runs = result["workflow_runs"] if isinstance(result, dict) else result
+        if not page_runs:
+            break
+        runs.extend(page_runs)
+        if len(page_runs) < _PAGE_SIZE:
+            break
+        page += 1
+    return runs
+
+
+def cancel_run(repo: str, run_id: int, token: str, base_url: str) -> bool:
+    """Cancel a CI run. Returns True on success."""
+    try:
+        _api_request(
+            "POST",
+            f"/repos/{repo}/actions/runs/{run_id}/cancel",
+            token,
+            base_url,
+        )
+    except (urllib.error.HTTPError, urllib.error.URLError):
+        return False
+    return True
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Cancel superseded CI runs for the same PR.")
+    parser.add_argument("--repo", required=True, help="owner/repo")
+    parser.add_argument("--current-run-id", required=True, help="Current run ID (not cancelled)")
+    parser.add_argument("--head-branch", required=True, help="PR head branch name")
+    parser.add_argument("--dry-run", action="store_true", help="List without cancelling")
+    parser.add_argument(
+        "--base-url",
+        default=os.environ.get("GITEA_API_URL", "https://git.oblachno.oblachno.fyi"),
+        help="Gitea base URL",
+    )
+    args = parser.parse_args()
+
+    token = os.environ.get("CI_GITEA_API_TOKEN") or os.environ.get("CI_GITEA_TOKEN")
+    if not token:
+        _log("No CI_GITEA_API_TOKEN or CI_GITEA_TOKEN set — skipping")
+        return 0
+
+    current_run_id = int(args.current_run_id)
+
+    _log(f"Listing running PR runs for {args.repo}...")
+    try:
+        runs = list_running_runs(args.repo, token, args.base_url)
+    except urllib.error.HTTPError as e:
+        if e.code in (_HTTP_NOT_FOUND, _HTTP_BAD_REQUEST):
+            _log(
+                f"Actions runs API not usable (HTTP {e.code}) — "
+                f"Gitea {args.base_url} may not support this endpoint or status filter. "
+                f"Skipping cancel-superseded (non-fatal)."
+            )
+            return 0
+        raise
+    _log(f"Found {len(runs)} running PR runs")
+
+    # Group by head_branch — only cancel runs for the SAME branch
+    # that are older than the current run
+    same_branch_runs = [
+        r
+        for r in runs
+        if r.get("head_branch") == args.head_branch
+        and int(r.get("id", 0)) != current_run_id
+        and int(r.get("id", 0)) < current_run_id
+    ]
+
+    if not same_branch_runs:
+        _log(f"No superseded runs for branch {args.head_branch}")
+        return 0
+
+    _log(f"Found {len(same_branch_runs)} superseded run(s) for branch {args.head_branch}:")
+    for r in same_branch_runs:
+        run_id = r.get("id")
+        created = r.get("created_at", "?")
+        _log(f"  Run #{run_id} (created: {created})")
+
+    if args.dry_run:
+        _log("[dry-run] Would cancel the above runs")
+        return 0
+
+    cancelled = 0
+    for r in same_branch_runs:
+        run_id = int(r["id"])
+        _log(f"Cancelling run #{run_id}...")
+        if cancel_run(args.repo, run_id, token, args.base_url):
+            cancelled += 1
+            _log(f"  Cancelled run #{run_id}")
+        else:
+            _log(f"  Failed to cancel run #{run_id}")
+
+    _log(f"Cancelled {cancelled}/{len(same_branch_runs)} superseded runs")
+    return 0
+
+
+if __name__ == "__main__":  # pragma: no cover
+    raise SystemExit(main())

src/devx/ci/check_auto_merge_ready.py

@@ -285,6 +285,26 @@ def cli(
         click.echo("=" * 60, err=True)
         for e in errors:
             click.echo(f"  - {e}", err=True)
+
+        # Remediation hints for the most common failure: PR title format
+        title_errors = [
+            e for e in errors if "PR title must follow format" in str(e) or "PR title task ID mismatch" in str(e)
+        ]
+        if title_errors and pr_number is not None and repo is not None:
+            click.echo("", err=True)
+            click.echo("REMEDIATION:", err=True)
+            click.echo(
+                _(
+                    "  Fix the PR title with:\n"
+                    "    python3 -m devx.ci.fix_pr_title --repo {repo} --pr-number {pr}\n"
+                    "  Or manually set the PR title to: '{expected}'",
+                    repo=repo,
+                    pr=pr_number,
+                    expected=f"{task_id}: <Vikunja task title>",
+                ),
+                err=True,
+            )
+
         raise click.ClickException(_("Pre-merge validation failed."))
 
     click.echo("[pre-merge-check] All auto-merge preconditions satisfied.")

src/devx/ci/check_pr_size.py

@@ -0,0 +1,212 @@
+#!/usr/bin/env python3
+# Implements: REQ-2
+"""Check PR size and reject oversized PRs.
+
+Enforces max lines changed and max files changed to keep PRs small
+and deployable. Generated/excluded files are not counted.
+
+PRs with the ``refactoring`` label bypass the size check — large but
+legitimate refactoring PRs that touch many files in a coordinated way.
+
+Usage:
+    python -m devx.ci.check_pr_size --base origin/master --head HEAD \\
+        --repo oblachno-oss/grm --pr-number 123
+
+In CI, pass ``--github-output`` to set ``pr-size-ok`` and ``pr-size-detail``
+for downstream steps.
+"""
+
+from __future__ import annotations
+
+import subprocess  # nosec B404
+
+import click
+from dotenv import load_dotenv
+
+from devx.api_clients import GiteaClient
+from devx.ci._shared import write_github_output
+from devx.config import GITEA_API_URL
+from devx.i18n import _
+from devx.tokens import get_ci_token
+
+load_dotenv()
+
+# Files/patterns excluded from size counting (generated, badges, locks, etc.)
+DEFAULT_EXCLUDED_PATTERNS = [
+    "CHANGELOG.md",
+    "README.md",
+    "docs/index.md",
+    "*.svg",
+    "uv.lock",
+    "poetry.lock",
+    "Pipfile.lock",
+    "package-lock.json",
+    "yarn.lock",
+    "go.sum",
+]
+
+DEFAULT_MAX_LINES = 500
+DEFAULT_MAX_FILES = 10
+REFACTORING_LABEL = "refactoring"
+
+
+def has_refactoring_label(repo: str, pr_number: int) -> bool:
+    """Check if a PR has the 'refactoring' label (bypasses size check)."""
+    try:
+        token = get_ci_token()
+        owner, repo_name = repo.split("/", 1)
+        client = GiteaClient(GITEA_API_URL, token, owner, repo_name)
+        pr = client.get_pr(pr_number)
+        labels = pr.get("labels", [])
+        return any(label.get("name") == REFACTORING_LABEL for label in labels)
+    except Exception:
+        return False
+
+
+def get_diff_stats(base: str, head: str) -> list[tuple[str, int, int]]:
+    """Get per-file diff stats (additions, deletions) between base and head.
+
+    Returns a list of (filename, additions, deletions) tuples.
+    """
+    result = subprocess.run(  # nosec B603 B607
+        ["git", "diff", "--numstat", base, head],
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+    if result.returncode != 0:
+        raise click.ClickException(_("git diff --numstat failed: {stderr}", stderr=result.stderr.strip()))
+    stats: list[tuple[str, int, int]] = []
+    for line in result.stdout.strip().split("\n"):
+        if not line:
+            continue
+        parts = line.split("\t")
+        if len(parts) != 3:
+            continue
+        additions_s, deletions_s, filename = parts
+        # Binary files show "-" for additions/deletions
+        additions = int(additions_s) if additions_s.isdigit() else 0
+        deletions = int(deletions_s) if deletions_s.isdigit() else 0
+        stats.append((filename, additions, deletions))
+    return stats
+
+
+def is_excluded(filename: str, excluded_patterns: list[str]) -> bool:
+    """Check if a filename matches any excluded pattern."""
+    from fnmatch import fnmatch
+
+    return any(fnmatch(filename, pat) for pat in excluded_patterns)
+
+
+def check_size(
+    stats: list[tuple[str, int, int]],
+    max_lines: int,
+    max_files: int,
+    excluded_patterns: list[str],
+) -> tuple[bool, str]:
+    """Check diff stats against limits.
+
+    Returns (is_ok, detail_message).
+    """
+    included = [(f, a, d) for f, a, d in stats if not is_excluded(f, excluded_patterns)]
+    total_lines = sum(a + d for _, a, d in included)
+    total_files = len(included)
+
+    if total_files == 0:
+        return True, "No non-excluded files changed"
+
+    if total_files > max_files:
+        return False, _(
+            "PR has {file_count} files changed (max {max_files}). Excluded: {excluded_count} files.",
+            file_count=total_files,
+            max_files=max_files,
+            excluded_count=len(stats) - total_files,
+        )
+
+    if total_lines > max_lines:
+        return False, _(
+            "PR has {line_count} lines changed (max {max_lines}). Excluded: {excluded_count} files.",
+            line_count=total_lines,
+            max_lines=max_lines,
+            excluded_count=len(stats) - total_files,
+        )
+
+    return True, _(
+        "PR size OK: {file_count} files, {line_count} lines (max {max_files} files, {max_lines} lines).",
+        file_count=total_files,
+        line_count=total_lines,
+        max_files=max_files,
+        max_lines=max_lines,
+    )
+
+
+@click.command()
+@click.option("--base", default="origin/master", help=_("Base ref for diff"))
+@click.option("--head", default="HEAD", help=_("Head ref for diff"))
+@click.option(
+    "--max-lines",
+    type=int,
+    default=DEFAULT_MAX_LINES,
+    help=_("Max lines changed (excluded files not counted)"),
+)
+@click.option(
+    "--max-files",
+    type=int,
+    default=DEFAULT_MAX_FILES,
+    help=_("Max files changed (excluded files not counted)"),
+)
+@click.option(
+    "--github-output",
+    "github_output",
+    is_flag=True,
+    default=False,
+    help=_("Write results to $GITHUB_OUTPUT"),
+)
+@click.option(
+    "--excluded",
+    "excluded",
+    multiple=True,
+    help=_("Additional excluded patterns (in addition to defaults)"),
+)
+@click.option("--repo", default=None, help=_("Repo (owner/name) for label check"))
+@click.option("--pr-number", type=int, default=None, help=_("PR number for label check"))
+def cli(
+    base: str,
+    head: str,
+    max_lines: int,
+    max_files: int,
+    github_output: bool,
+    excluded: tuple[str, ...],
+    repo: str | None,
+    pr_number: int | None,
+) -> None:
+    """Check PR size and reject oversized PRs."""
+    # Check for refactoring label bypass
+    if repo and pr_number and has_refactoring_label(repo, pr_number):
+        detail = _("PR has 'refactoring' label — size check bypassed.")
+        if github_output:
+            write_github_output("pr-size-ok", "true")
+            write_github_output("pr-size-detail", detail)
+        click.echo(f"[pr-size] {detail}")
+        return
+
+    excluded_patterns = list(DEFAULT_EXCLUDED_PATTERNS) + list(excluded)
+    stats = get_diff_stats(base, head)
+    is_ok, detail = check_size(stats, max_lines, max_files, excluded_patterns)
+
+    if github_output:
+        write_github_output("pr-size-ok", "true" if is_ok else "false")
+        write_github_output("pr-size-detail", detail)
+
+    if is_ok:
+        click.echo(f"[pr-size] {detail}")
+    else:
+        click.echo(f"[pr-size] FAILED: {detail}", err=True)
+        click.echo("", err=True)
+        click.echo("Oversized PRs cannot be reliably reviewed or deployed independently.", err=True)
+        click.echo("Split your work into smaller PRs, each addressing one concern.", err=True)
+        raise click.ClickException(_("PR size check failed."))
+
+
+if __name__ == "__main__":  # pragma: no cover
+    cli()

src/devx/ci/check_workflow_artifact_deps.py

@@ -0,0 +1,163 @@
+"""Check that workflow jobs downloading artifacts depend on the uploading job.
+
+This prevents the class of bug where a job downloads an artifact produced by
+another job but does not declare that job in its ``needs`` list. When both
+jobs run in parallel, the download fails because the artifact hasn't been
+uploaded yet.
+
+The check scans all workflow YAML files for:
+  - ``gitea-upload-artifact`` / ``actions/upload-artifact`` steps
+  - ``gitea-download-artifact`` / ``actions/download-artifact`` steps
+
+For each download, it finds the job(s) that upload an artifact with a
+matching name and verifies that at least one uploading job is in the
+downloading job's ``needs`` list.
+
+Artifact names with ``${{ ... }}`` expressions are matched literally
+(both sides use the same expression, so they resolve to the same value
+at runtime).
+
+Usage::
+
+    python -m devx.ci.check_workflow_artifact_deps
+    python -m devx.ci.check_workflow_artifact_deps --workflow .gitea/workflows/ci.yml
+
+Exit code 0 if all artifact dependencies are satisfied, 1 otherwise.
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+import click
+import yaml
+
+REPO_ROOT = Path.cwd()
+WORKFLOWS_DIR = REPO_ROOT / ".gitea" / "workflows"
+
+UPLOAD_ACTIONS = ("upload-artifact",)
+DOWNLOAD_ACTIONS = ("download-artifact",)
+
+
+def _is_artifact_action(uses: str, action_types: tuple[str, ...]) -> bool:
+    """Check if a step's ``uses`` field references an artifact action."""
+    if not uses:
+        return False
+    uses_lower = uses.lower()
+    return any(action in uses_lower for action in action_types)
+
+
+def _extract_artifact_info(workflow: dict) -> tuple[dict[str, list[str]], list[tuple[str, str, str]]]:
+    """Extract artifact upload and download info from a workflow.
+
+    Returns:
+        uploads: Mapping of artifact_name → list of job names that upload it.
+        downloads: List of (job_name, artifact_name, step_name) tuples.
+    """
+    uploads: dict[str, list[str]] = {}
+    downloads: list[tuple[str, str, str]] = []
+
+    jobs = workflow.get("jobs", {})
+    for job_name, job_def in jobs.items():
+        for step in job_def.get("steps", []):
+            uses = step.get("uses", "")
+            with_data = step.get("with", {})
+            artifact_name = with_data.get("name", "")
+            step_name = step.get("name", "")
+
+            if _is_artifact_action(uses, UPLOAD_ACTIONS):
+                if artifact_name:
+                    uploads.setdefault(artifact_name, []).append(job_name)
+            elif _is_artifact_action(uses, DOWNLOAD_ACTIONS) and artifact_name:
+                downloads.append((job_name, artifact_name, step_name))
+
+    return uploads, downloads
+
+
+def _check_workflow(filepath: Path) -> list[str]:
+    """Check a single workflow file for missing artifact dependencies.
+
+    Returns a list of error messages (empty if all OK).
+    """
+    errors: list[str] = []
+    content = filepath.read_text(encoding="utf-8")
+    try:
+        workflow = yaml.safe_load(content)
+    except yaml.YAMLError as exc:
+        return [f"{filepath}: cannot parse YAML: {exc}"]
+
+    if not isinstance(workflow, dict):
+        return [f"{filepath}: not a valid workflow (expected dict)"]
+
+    uploads, downloads = _extract_artifact_info(workflow)
+    jobs = workflow.get("jobs", {})
+
+    for dl_job, artifact_name, step_name in downloads:
+        uploading_jobs = uploads.get(artifact_name, [])
+        if not uploading_jobs:
+            # Artifact not uploaded in this workflow — may come from an
+            # external source (e.g., S3). Skip.
+            continue
+
+        dl_job_def = jobs.get(dl_job, {})
+        needs_raw = dl_job_def.get("needs", [])
+        needs = {needs_raw} if isinstance(needs_raw, str) else set(needs_raw or [])
+
+        # Check if any uploading job is in the download job's needs
+        if not any(uploader in needs for uploader in uploading_jobs):
+            # Check if the download step has continue-on-error: true
+            # (valid guard when the uploading job may be skipped due to
+            # Gitea Actions' needs skip behavior — the download will
+            # fail gracefully if the artifact doesn't exist).
+            dl_steps = dl_job_def.get("steps", [])
+            step_def = next((s for s in dl_steps if s.get("name", "") == step_name), {})
+            if step_def.get("continue-on-error") is True:
+                continue
+
+            uploaders_str = ", ".join(sorted(uploading_jobs))
+            errors.append(
+                f"{filepath.name}::{dl_job}: step '{step_name}' downloads "
+                f"artifact '{artifact_name}' produced by job(s) "
+                f"[{uploaders_str}] but none are in its 'needs' list "
+                f"(current needs: {sorted(needs) or 'none'}). "
+                f"Add the uploading job to 'needs' or guard the download "
+                f"with an if: condition checking the upload job's result."
+            )
+
+    return errors
+
+
+@click.command()
+@click.option(
+    "--workflow",
+    type=click.Path(exists=True, path_type=Path),
+    help="Check a specific workflow file (default: all in .gitea/workflows/).",
+)
+@click.option(
+    "--workflows-dir",
+    type=click.Path(exists=True, path_type=Path),
+    default=None,
+    help="Override the workflows directory (default: .gitea/workflows/).",
+)
+def main(workflow: Path | None, workflows_dir: Path | None) -> None:
+    """Check that artifact download jobs depend on upload jobs."""
+    wdir = workflows_dir or WORKFLOWS_DIR
+    files = [workflow] if workflow else sorted(wdir.glob("*.yml"))
+
+    all_errors: list[str] = []
+    for f in files:
+        errors = _check_workflow(f)
+        all_errors.extend(errors)
+
+    if all_errors:
+        click.echo("[check-workflow-artifact-deps] FAIL: missing artifact dependencies found:")
+        for err in all_errors:
+            click.echo(f"  - {err}")
+        sys.exit(1)
+    else:
+        click.echo("[check-workflow-artifact-deps] OK: all artifact downloads have upload jobs in needs.")
+
+
+if __name__ == "__main__":  # pragma: no cover
+    main()

src/devx/ci/check_workflow_tofu_init.py

@@ -0,0 +1,145 @@
+"""Check that workflow jobs using tofu state have a tofu-init step.
+
+This prevents the class of bug where a job runs ``tofu output`` or calls
+a script that uses tofu state without first running ``tofu init``,
+causing "Required plugins are not installed" errors.
+
+The check scans all workflow YAML files for jobs that:
+  - Call scripts that use ``tofu output`` (configurable via --state-scripts)
+  - Call ``tofu output`` directly
+  - Call ``tofu plan`` or ``tofu apply`` directly
+
+For each such job, it verifies the same job has a ``tofu-init`` step,
+either:
+  - Directly via ``tofu init`` in a step's run command
+  - Via ``create_staging_deployment.py --phase tofu-init``
+  - Via ``create_production_deployment.py --phase tofu-init``
+
+Usage::
+
+    python -m devx.ci.check_workflow_tofu_init
+    python -m devx.ci.check_workflow_tofu_init --workflow .gitea/workflows/deploy.yml
+
+Exit code 0 if all jobs have tofu-init, 1 otherwise.
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+import click
+import yaml
+
+REPO_ROOT = Path.cwd()
+WORKFLOWS_DIR = REPO_ROOT / ".gitea" / "workflows"
+
+# Scripts that call `tofu output`, `tofu plan`, or `tofu apply` internally.
+# If a job calls any of these, it must have a tofu-init step.
+# NOTE: destroy_orphans.py reads terraform.tfstate directly from disk
+# (does not invoke `tofu output`), so it does NOT need tofu-init.
+DEFAULT_TOFU_STATE_SCRIPTS: set[str] = {
+    "preflight_deploy.py",
+}
+
+# Commands that directly use tofu state (must be preceded by tofu init).
+TOFU_STATE_COMMANDS = ("tofu output", "tofu plan", "tofu apply", "tofu show")
+
+# Commands that initialize tofu (counted as tofu-init steps).
+TOFU_INIT_COMMANDS = (
+    "tofu init",
+    "--phase tofu-init",
+    "tofu-init",
+)
+
+
+def _check_workflow(filepath: Path, state_scripts: set[str]) -> list[str]:
+    """Check a single workflow file for missing tofu-init steps.
+
+    Returns a list of error messages (empty if all OK).
+    """
+    errors: list[str] = []
+    content = filepath.read_text(encoding="utf-8")
+    try:
+        workflow = yaml.safe_load(content)
+    except yaml.YAMLError as exc:
+        return [f"{filepath}: cannot parse YAML: {exc}"]
+
+    jobs = workflow.get("jobs", {})
+    for job_name, job_def in jobs.items():
+        steps = job_def.get("steps", [])
+        if not steps:
+            continue
+
+        uses_tofu_state = False
+        has_tofu_init = False
+
+        for step in steps:
+            run_cmd = step.get("run", "")
+            if not run_cmd:
+                continue
+            # Check if this step uses tofu state
+            for script in state_scripts:
+                if script in run_cmd:
+                    uses_tofu_state = True
+            for cmd in TOFU_STATE_COMMANDS:
+                if cmd in run_cmd:
+                    uses_tofu_state = True
+            # Check if this step initializes tofu
+            for cmd in TOFU_INIT_COMMANDS:
+                if cmd in run_cmd:
+                    has_tofu_init = True
+
+        if uses_tofu_state and not has_tofu_init:
+            errors.append(
+                f"{filepath.name}::{job_name}: uses tofu state "
+                f"(tofu output/plan/apply or {state_scripts}) "
+                f"but has no tofu-init step. Add a step running "
+                f"'create_*_deployment.py --phase tofu-init' before "
+                f"the first tofu state access."
+            )
+
+    return errors
+
+
+@click.command()
+@click.option(
+    "--workflow",
+    type=click.Path(exists=True, path_type=Path),
+    help="Check a specific workflow file (default: all in .gitea/workflows/).",
+)
+@click.option(
+    "--workflows-dir",
+    type=click.Path(exists=True, path_type=Path),
+    default=None,
+    help="Override the workflows directory (default: .gitea/workflows/).",
+)
+@click.option(
+    "--state-script",
+    "state_scripts",
+    multiple=True,
+    default=None,
+    help="Add a script name that uses tofu state (can be repeated). Overrides the default list if any are specified.",
+)
+def main(workflow: Path | None, workflows_dir: Path | None, state_scripts: tuple[str, ...]) -> None:
+    """Check that workflow jobs using tofu state have a tofu-init step."""
+    scripts = set(state_scripts) if state_scripts else DEFAULT_TOFU_STATE_SCRIPTS
+    wdir = workflows_dir or WORKFLOWS_DIR
+    files = [workflow] if workflow else sorted(wdir.glob("*.yml"))
+
+    all_errors: list[str] = []
+    for f in files:
+        errors = _check_workflow(f, scripts)
+        all_errors.extend(errors)
+
+    if all_errors:
+        click.echo("[check-workflow-tofu-init] FAIL: missing tofu-init steps found:")
+        for err in all_errors:
+            click.echo(f"  - {err}")
+        sys.exit(1)
+    else:
+        click.echo("[check-workflow-tofu-init] OK: all tofu-state jobs have tofu-init.")
+
+
+if __name__ == "__main__":  # pragma: no cover
+    main()

src/devx/ci/create_dependency_pr.py

@@ -0,0 +1,227 @@
+#!/usr/bin/env python3
+# Implements: REQ-5
+"""Auto-create an infra PR to bump a pinned dependency version.
+
+After grm or sso-bridge publishes a new package version, this module
+creates a PR in the infra repo to bump the pinned version in
+``pyproject.toml`` or ``ansible/group_vars/all/images.yml``.
+
+Reuses ``devx.tools.create_pr`` for PR creation and Vikunja task linking.
+
+Usage:
+    python -m devx.ci.create_dependency_pr \
+        --repo oblachno/infra \
+        --package grm \
+        --new-version 0.5.2 \
+        --source-repo oblachno/grm \
+        --source-run-id 12345
+"""
+
+from __future__ import annotations
+
+import re
+import subprocess  # nosec B404
+from pathlib import Path
+
+import click
+from dotenv import load_dotenv
+
+from devx.api_clients import GiteaClient
+from devx.config import GITEA_API_URL, VIKUNJA_API_URL, VIKUNJA_PROJECT_ID
+from devx.exceptions import APIError
+from devx.i18n import _
+from devx.tokens import get_ci_token, get_vikunja_token
+from devx.tools.create_pr import find_existing_pr
+
+load_dotenv()
+
+# Where infra pins dependency versions
+PYPROJECT_PATH = "pyproject.toml"
+IMAGES_YML_PATH = "ansible/group_vars/all/images.yml"
+ROLE_DEFAULTS_PATH = "ansible/roles/sso_bridge/defaults/main.yml"
+
+
+def find_pinned_version(package: str, file_path: str) -> str | None:
+    """Find the currently pinned version of a package in a file.
+
+    Looks for patterns like:
+    - ``"grm @ git+...@v0.5.1"``
+    - ``grm = "0.5.1"``
+    - ``grm_version: "0.5.1"``
+    - ``grm_image_version: "0.5.1"``
+    """
+    path = Path(file_path)
+    if not path.exists():
+        return None
+    content = path.read_text(encoding="utf-8")
+    # Match various pinning patterns
+    patterns = [
+        rf"{package}\s*@\s*git\+[^@]+@v?([\d.]+)",  # pip: package @ git+url@vX.Y.Z
+        rf'{package}\s*=\s*"([\d.]+)"',  # pyproject: package = "X.Y.Z"
+        rf'{package}_version:\s*"([\d.]+)"',  # ansible vars: package_version: "X.Y.Z"
+        rf'{package}_image_version:\s*"([\d.]+)"',  # ansible vars: package_image_version: "X.Y.Z"
+    ]
+    for pat in patterns:
+        match = re.search(pat, content)
+        if match:
+            return match.group(1)
+    return None
+
+
+def update_pinned_version(file_path: str, package: str, old_version: str, new_version: str) -> bool:
+    """Update the pinned version in a file. Returns True if changed."""
+    path = Path(file_path)
+    if not path.exists():
+        return False
+    content = path.read_text(encoding="utf-8")
+    # Replace old version with new version in package-related lines
+    patterns = [
+        (rf"({package}\s*@\s*git\+[^@]+@v?){old_version}", rf"\g<1>{new_version}"),
+        (rf'({package}\s*=\s*"){old_version}(")', rf"\g<1>{new_version}\g<2>"),
+        (rf'({package}_version:\s*"){old_version}(")', rf"\g<1>{new_version}\g<2>"),
+        (rf'({package}_image_version:\s*"){old_version}(")', rf"\g<1>{new_version}\g<2>"),
+    ]
+    new_content = content
+    changed = False
+    for pat, replacement in patterns:
+        new_content, n = re.subn(pat, replacement, new_content)
+        if n > 0:
+            changed = True
+    if changed:
+        path.write_text(new_content, encoding="utf-8")
+    return changed
+
+
+def create_vikunja_task(title: str, description: str) -> str | None:
+    """Create a Vikunja task and return its identifier (e.g., OBL-INFRA-531)."""
+    try:
+        token = get_vikunja_token()
+    except click.ClickException:
+        return None
+
+    from devx.api_clients import VikunjaClient
+
+    client = VikunjaClient(VIKUNJA_API_URL, token)
+    task = client.create_task(VIKUNJA_PROJECT_ID, title=title, description=description)
+    return str(task.get("identifier", ""))
+
+
+@click.command()
+@click.option("--repo", default="oblachno/infra", help=_("Target repo (owner/name) to create PR in"))
+@click.option("--package", required=True, help=_("Package name to bump (e.g., grm, sso-bridge)"))
+@click.option("--new-version", required=True, help=_("New version to pin"))
+@click.option("--source-repo", required=True, help=_("Source repo that published (owner/name)"))
+@click.option("--source-run-id", default="", help=_("CI run ID that triggered the publish"))
+@click.option("--dry-run", is_flag=True, default=False, help=_("Show what would be done without creating PR"))
+def cli(
+    repo: str,
+    package: str,
+    new_version: str,
+    source_repo: str,
+    source_run_id: str,
+    dry_run: bool,
+) -> None:
+    """Create an infra PR to bump a pinned dependency version."""
+    token = get_ci_token()
+    if "/" not in repo:
+        raise click.ClickException(_("Invalid repo format: {repo}", repo=repo))
+    owner, repo_name = repo.split("/", 1)
+    client = GiteaClient(GITEA_API_URL, token, owner, repo_name)
+
+    # Find current pinned version
+    old_version = None
+    changed_file = None
+    for f in [PYPROJECT_PATH, IMAGES_YML_PATH, ROLE_DEFAULTS_PATH]:
+        old_version = find_pinned_version(package, f)
+        if old_version:
+            changed_file = f
+            break
+
+    if not old_version:
+        click.echo(_("[dep-pr] Could not find pinned version for {pkg} in infra repo.", pkg=package))
+        if dry_run:
+            return
+        raise click.ClickException(_("Could not find pinned version for {pkg}", pkg=package))
+
+    if old_version == new_version:
+        click.echo(_("[dep-pr] {pkg} already at {version} — no PR needed.", pkg=package, version=new_version))
+        return
+
+    click.echo(
+        _(
+            "[dep-pr] Bumping {pkg} from {old} to {new} in {file}",
+            pkg=package,
+            old=old_version,
+            new=new_version,
+            file=changed_file,
+        )
+    )
+
+    if dry_run:
+        click.echo(f"[dep-pr] DRY RUN: would update {changed_file} and create PR")
+        return
+
+    # Create a branch
+    branch_name = f"deps/{package}-{new_version}"
+    base_branch = "master"
+
+    # Check for existing PR (reuse from tools.create_pr)
+    existing = find_existing_pr(client, branch_name)
+    if existing:
+        click.echo(_("[dep-pr] PR already exists: #{number}", number=existing.get("number", "?")))
+        return
+
+    # Create branch via API
+    try:
+        master_ref = client._request("GET", "/git/refs/heads/master").json()
+        master_sha = master_ref.get("object", {}).get("sha", "")
+        if not master_sha:
+            raise click.ClickException("Could not get master SHA")
+        client._request("POST", "/git/refs", json={"ref": f"refs/heads/{branch_name}", "sha": master_sha})
+    except APIError as e:
+        if "already exists" in str(e).lower():
+            click.echo(f"[dep-pr] Branch {branch_name} already exists")
+        else:
+            raise click.ClickException(_("Failed to create branch: {error}", error=str(e))) from None
+
+    # Clone, update file, commit, push
+    subprocess.run(["git", "fetch", "origin", f"{branch_name}"], check=False, capture_output=True)  # nosec B603 B607
+    subprocess.run(["git", "checkout", branch_name], check=False, capture_output=True)  # nosec B603 B607
+
+    if not changed_file or not update_pinned_version(changed_file, package, old_version, new_version):
+        raise click.ClickException(_("Failed to update {file}", file=changed_file))
+
+    subprocess.run(["git", "add", changed_file], check=True)  # nosec B603 B607
+    commit_msg = f"deps: bump {package} from {old_version} to {new_version}"
+    subprocess.run(["git", "commit", "-m", commit_msg], check=True)  # nosec B603 B607
+    subprocess.run(["git", "push", "origin", branch_name], check=True)  # nosec B603 B607
+
+    # Create Vikunja task for tracking
+    task_title = f"Bump {package} to {new_version}"
+    task_desc = (
+        f"<p>Auto-created dependency bump PR.</p>"
+        f"<p>Package: {package}</p>"
+        f"<p>Version: {old_version} → {new_version}</p>"
+        f"<p>Source: {source_repo} (run #{source_run_id})</p>"
+    )
+    task_id = create_vikunja_task(task_title, task_desc)
+
+    # Create PR directly (dependency PRs have custom titles, not Vikunja-derived)
+    pr_title = f"{task_id}: {task_title}" if task_id else task_title
+    pr_body = (
+        f"## Dependency Bump\n\n"
+        f"Bumps **{package}** from `{old_version}` to `{new_version}`.\n\n"
+        f"- **Source**: {source_repo}\n"
+        f"- **Triggered by**: CI run #{source_run_id}\n"
+        f"- **Changed file**: `{changed_file}`\n\n"
+        f"This PR was auto-created by `devx.ci.create_dependency_pr`.\n"
+    )
+    if task_id:
+        pr_body += f"\nCloses {task_id}"
+
+    pr = client.create_pr(title=pr_title, head=branch_name, base=base_branch, body=pr_body)
+    click.echo(_("[dep-pr] Created PR #{number}: {title}", number=pr.get("number", "?"), title=pr_title))
+
+
+if __name__ == "__main__":  # pragma: no cover
+    cli()

src/devx/ci/doc_coverage.py

@@ -44,7 +44,6 @@ REQUIRED_SCRIPTS = [
     "auto_merge.py",
     "release.py",
     "publish.py",
-    "pr_review.py",
     "notify_failure.py",
     "post_merge.py",
     "classify_changes.py",
@@ -52,7 +51,6 @@ REQUIRED_SCRIPTS = [
     "detect_release_commit.py",
     "push_badges.py",
     "distribute_molecule.py",
-    "molecule_ci_guard.py",
     "validate_commit_msg.py",
 ]
 

src/devx/ci/fast_molecule.py

@@ -0,0 +1,121 @@
+#!/usr/bin/env python3
+# Implements: REQ-3
+"""Detect changed Ansible roles and output fast molecule test commands.
+
+Reuses ``devx.molecule.molecule_changed`` for role detection (which handles
+playbook→role mapping and shared infrastructure paths).
+
+Fast molecule = converge + verify only, single platform, no idempotence
+check. Used in pre-merge CI to get quick feedback on Ansible changes
+without running the full molecule suite (which runs nightly).
+
+Usage:
+    python -m devx.ci.fast_molecule --base origin/master --head HEAD
+
+Outputs the list of changed roles and the molecule commands to run.
+In CI, pass ``--github-output`` to set ``fast-molecule-roles`` (space-
+separated) and ``fast-molecule-needed`` (true/false) for downstream steps.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import click
+from dotenv import load_dotenv
+
+from devx.ci._shared import write_github_output
+from devx.i18n import _
+from devx.molecule.molecule_changed import detect_changed_roles, get_changed_files
+
+load_dotenv()
+
+
+def get_molecule_scenarios(role_name: str, roles_dir: str = "ansible/roles") -> list[str]:
+    """Get list of molecule scenario names for a role."""
+    mol_dir = Path(roles_dir) / role_name / "molecule"
+    if not mol_dir.is_dir():
+        return []
+    scenarios = []
+    for p in mol_dir.iterdir():
+        if p.is_dir() and (p / "molecule.yml").exists():
+            scenarios.append(p.name)
+    return sorted(scenarios)
+
+
+def build_molecule_commands(
+    roles: set[str],
+    roles_dir: str = "ansible/roles",
+    platform: str = "ubuntu-2604",
+) -> list[str]:
+    """Build molecule test commands for changed roles.
+
+    For each role, runs each scenario with converge + verify only
+    (skip create/destroy between scenarios, skip idempotence).
+    """
+    commands: list[str] = []
+    for role in sorted(roles):
+        scenarios = get_molecule_scenarios(role, roles_dir)
+        if not scenarios:
+            continue
+        for scenario in scenarios:
+            cmd = f"molecule test -s {scenario} --destroy=never --platform-name={platform}"
+            commands.append(cmd)
+    return commands
+
+
+@click.command()
+@click.option("--base", default="origin/master", help=_("Base ref for diff"))
+@click.option("--head", default="HEAD", help=_("Head ref for diff"))
+@click.option("--roles-dir", default="ansible/roles", help=_("Directory containing Ansible roles"))
+@click.option("--platform", default="ubuntu-2604", help=_("Single platform to test against"))
+@click.option(
+    "--github-output",
+    "github_output",
+    is_flag=True,
+    default=False,
+    help=_("Write results to $GITHUB_OUTPUT"),
+)
+def cli(
+    base: str,
+    head: str,
+    roles_dir: str,
+    platform: str,
+    github_output: bool,
+) -> None:
+    """Detect changed roles and output fast molecule test commands."""
+    # Use molecule_changed for role detection (handles playbooks, shared infra)
+    files = get_changed_files(base)
+    if not files:
+        click.echo("[fast-molecule] No files changed.")
+        if github_output:
+            write_github_output("fast-molecule-needed", "false")
+            write_github_output("fast-molecule-roles", "")
+        return
+
+    roles = detect_changed_roles(files)
+    if not roles:
+        click.echo("[fast-molecule] No Ansible roles changed.")
+        if github_output:
+            write_github_output("fast-molecule-needed", "false")
+            write_github_output("fast-molecule-roles", "")
+        return
+
+    commands = build_molecule_commands(roles, roles_dir, platform)
+
+    if github_output:
+        write_github_output("fast-molecule-needed", "true" if commands else "false")
+        write_github_output("fast-molecule-roles", " ".join(sorted(roles)))
+
+    click.echo(_("[fast-molecule] Changed roles: {roles}", roles=", ".join(sorted(roles))))
+    if not commands:
+        click.echo("[fast-molecule] No molecule scenarios found for changed roles.")
+        return
+
+    click.echo(f"[fast-molecule] {len(commands)} scenario(s) to run:")
+    for cmd in commands:
+        click.echo(f"  {cmd}")
+
+
+if __name__ == "__main__":  # pragma: no cover
+    cli()

src/devx/ci/fix_pr_title.py

@@ -0,0 +1,127 @@
+#!/usr/bin/env python3
+"""Auto-fix PR title to follow the ``{PREFIX}-N: <title>`` convention.
+
+Reads the task ID from the branch name, fetches the Vikunja task title,
+and updates the PR title via the Gitea API.
+
+Exit codes:
+  0 = PR title updated (or already correct)
+  1 = Error (missing token, PR not found, etc.)
+
+Usage::
+
+    python3 -m devx.ci.fix_pr_title --repo owner/repo --pr-number 123
+    python3 -m devx.ci.fix_pr_title --repo owner/repo --branch DEVX-256-fix-foo --pr-number 123
+"""
+
+from __future__ import annotations
+
+import click
+from dotenv import load_dotenv  # pyright: ignore[reportMissingImports,reportUnknownVariableType]
+
+from devx.api_clients import GiteaClient
+from devx.ci.auto_merge import extract_task_id
+from devx.ci.check_auto_merge_ready import get_vikunja_title_optional
+from devx.config import (
+    GITEA_API_URL,
+    TASK_PREFIX,
+)
+from devx.exceptions import APIError
+from devx.i18n import _
+from devx.tokens import get_ci_token
+
+load_dotenv()
+
+
+@click.command()
+@click.option("--repo", required=True, help=_("Repository in owner/name format"))
+@click.option("--pr-number", type=int, required=True, help=_("PR number to fix"))
+@click.option("--branch", default=None, help=_("Branch name (auto-fetched from PR if not given)"))
+@click.option("--dry-run", is_flag=True, help=_("Show what would change without updating"))
+def cli(repo: str, pr_number: int, branch: str | None, dry_run: bool) -> None:
+    """Fix PR title to follow the ``{PREFIX}-N: <title>`` convention."""
+    if "/" not in repo:
+        raise click.ClickException(_("Repo must be in 'owner/name' format, got: {repo}", repo=repo))
+    owner, repo_name = repo.split("/", 1)
+
+    # 1. Get CI token
+    try:
+        token = get_ci_token()
+    except click.ClickException as exc:
+        raise click.ClickException(_("CI_GITEA_API_TOKEN not set: {error}", error=str(exc))) from exc
+
+    client = GiteaClient(GITEA_API_URL, token, owner, repo_name)
+
+    # 2. Fetch PR
+    try:
+        pr = client.get_pr(pr_number)
+    except APIError as exc:
+        raise click.ClickException(_("Failed to fetch PR #{pr}: {error}", pr=pr_number, error=str(exc))) from exc
+
+    current_title = str(pr.get("title", ""))
+    if not branch:
+        branch = str(pr.get("head", {}).get("ref", ""))
+        if not branch:
+            raise click.ClickException(_("Could not determine branch name from PR #{pr}", pr=pr_number))
+
+    click.echo(f"[fix-pr-title] Branch: {branch}")
+    click.echo(f"[fix-pr-title] Current PR title: {current_title}")
+
+    # 3. Extract task ID from branch
+    task_id = extract_task_id(branch)
+    if not task_id:
+        raise click.ClickException(
+            _(
+                "No task ID found in branch '{branch}'. Expected format: {prefix}-N-description.",
+                branch=branch,
+                prefix=TASK_PREFIX,
+            )
+        )
+
+    click.echo(f"[fix-pr-title] Task ID: {task_id}")
+
+    # 4. Get Vikunja task title
+    vikunja_title = get_vikunja_title_optional(task_id)
+    if vikunja_title is None:
+        # Fallback: strip common prefixes from current title
+        # (e.g. "fix: ...", "feat: ...", "refactor: ...")
+        import re
+
+        stripped = re.sub(
+            r"^(fix|feat|refactor|chore|docs|test|ci|build|perf|style|revert)(\(.+?\))?!?:\s*", "", current_title
+        )
+        # Also strip any leading task ID prefix
+        stripped = re.sub(rf"^{TASK_PREFIX}-\d+:\s*", "", stripped)
+        vikunja_title = stripped if stripped else current_title
+        click.echo(f"[fix-pr-title] WARNING: Vikunja task not found — using stripped title: {vikunja_title}")
+    else:
+        click.echo(f"[fix-pr-title] Vikunja title: {vikunja_title}")
+
+    # 5. Build new title
+    # Defensive: strip task ID prefix from Vikunja title if present
+    if vikunja_title.startswith(f"{task_id}:"):
+        vikunja_title = vikunja_title[len(f"{task_id}:") :].strip()
+
+    new_title = f"{task_id}: {vikunja_title}"
+
+    if current_title == new_title:
+        click.echo(f"[fix-pr-title] PR title already correct: {new_title}")
+        return
+
+    click.echo(f"[fix-pr-title] New PR title: {new_title}")
+
+    if dry_run:
+        click.echo("[fix-pr-title] Dry run — not updating PR.")
+        return
+
+    # 6. Update PR title
+    try:
+        client.update_pr(pr_number, {"title": new_title})
+    except APIError as exc:
+        raise click.ClickException(_("Failed to update PR #{pr}: {error}", pr=pr_number, error=str(exc))) from exc
+
+    click.echo(f"[fix-pr-title] PR #{pr_number} title updated to: {new_title}")
+
+
+if __name__ == "__main__":  # pragma: no cover
+    cli()  # pragma: no cover

src/devx/ci/integration_guard.py

@@ -1,10 +1,9 @@
 #!/usr/bin/env python3
 """Run integration tests with cross-runner failure detection.
 
-Wraps ``pytest`` with the same Gitea API polling mechanism used by
-``molecule_ci_guard``. If any other integration-tests matrix runner
-reports failure, the current pytest subprocess is killed and this runner
-exits early with code 1.
+Wraps ``pytest`` with Gitea API polling. If any other integration-tests
+matrix runner reports failure, the current pytest subprocess is killed
+and this runner exits early with code 1.
 
 Usage::
 
@@ -35,17 +34,62 @@ import threading
 import time
 
 import click
+import requests
 
 from devx.config import REPO_NAME, REPO_OWNER
 from devx.i18n import _
-from devx.molecule.molecule_ci_guard import (
-    poll_for_other_failures,
-)
 from devx.tokens import get_ci_token
 
 POLL_INTERVAL = 10
 
 
+def get_running_jobs(gitea_url: str, owner: str, repo: str, token: str, run_id: int) -> list[dict]:
+    """Return jobs for the given workflow run."""
+    url = f"{gitea_url}/api/v1/repos/{owner}/{repo}/actions/runs/{run_id}/jobs"
+    headers = {"Authorization": f"token {token}"}
+    response = requests.get(url, headers=headers, timeout=30)
+    response.raise_for_status()
+    data = response.json()
+    return data.get("jobs", [])
+
+
+def any_other_runner_failed(jobs: list[dict], current_job_name: str, current_index: int) -> bool:
+    """Return True if any other matrix job has failed."""
+    for job in jobs:
+        name = job.get("name", "")
+        if not name.startswith(current_job_name):
+            continue
+        if name == f"{current_job_name} ({current_index})" or name == current_job_name:
+            continue
+        if job.get("conclusion") == "failure":
+            return True
+    return False
+
+
+def poll_for_other_failures(
+    gitea_url: str,
+    owner: str,
+    repo: str,
+    token: str,
+    run_id: int,
+    job_name: str,
+    current_index: int,
+    stop_event: threading.Event,
+    failed_event: threading.Event,
+) -> None:
+    """Background thread: poll API and signal if another runner fails."""
+    while not stop_event.is_set():
+        try:
+            jobs = get_running_jobs(gitea_url, owner, repo, token, run_id)
+            if any_other_runner_failed(jobs, job_name, current_index):
+                click.echo(_("Another runner failed. Stopping this runner early."))
+                failed_event.set()
+                return
+        except requests.RequestException as exc:
+            click.echo(_("API poll warning: {exc}", exc=exc))
+        stop_event.wait(POLL_INTERVAL)
+
+
 @click.command(context_settings={"ignore_unknown_options": True})
 @click.argument("pytest_args", nargs=-1, type=click.UNPROCESSED, required=True)
 def cli(pytest_args: tuple[str, ...]) -> None:

src/devx/ci/nightly_gate.py

@@ -0,0 +1,119 @@
+#!/usr/bin/env python3
+# Implements: REQ-4
+"""Check if the nightly CI gate has passed; block staging deploys if it failed.
+
+The nightly gate stores its status as a Gitea Actions repository variable
+named ``NIGHTLY_STATUS`` on the infra repo. Values:
+
+- ``passed`` — nightly molecule + staging deploy + integration tests passed.
+- ``failed:<run_id>`` — nightly failed. Staging deploys are blocked until
+  the nightly passes again.
+- (not set) — nightly hasn't run yet. First deploy is allowed (bootstrap).
+
+Usage:
+    python -m devx.ci.nightly_gate --repo oblachno/infra --action check
+    python -m devx.ci.nightly_gate --repo oblachno/infra --action set-passed --run-id 12345
+    python -m devx.ci.nightly_gate --repo oblachno/infra --action set-failed --run-id 12345
+"""
+
+from __future__ import annotations
+
+import click
+from dotenv import load_dotenv
+
+from devx.api_clients import GiteaClient
+from devx.ci._shared import write_github_output
+from devx.config import GITEA_API_URL
+from devx.i18n import _
+from devx.tokens import get_ci_token
+
+load_dotenv()
+
+NIGHTLY_STATUS_VAR = "NIGHTLY_STATUS"
+
+
+def get_nightly_status(client: GiteaClient) -> str:
+    """Get the nightly status variable. Returns empty string if not set."""
+    val = client.get_repo_variable(NIGHTLY_STATUS_VAR)
+    return val or ""
+
+
+def set_nightly_status(client: GiteaClient, status: str) -> None:
+    """Set the nightly status variable."""
+    client.set_repo_variable(NIGHTLY_STATUS_VAR, status)
+
+
+@click.command()
+@click.option("--repo", required=True, help=_("Repository in owner/name format"))
+@click.option(
+    "--action",
+    type=click.Choice(["check", "set-passed", "set-failed"]),
+    required=True,
+    help=_("Action to perform"),
+)
+@click.option("--run-id", default="", help=_("CI run ID (for set-failed/set-passed)"))
+@click.option(
+    "--github-output",
+    "github_output",
+    is_flag=True,
+    default=False,
+    help=_("Write results to $GITHUB_OUTPUT"),
+)
+def cli(repo: str, action: str, run_id: str, github_output: bool) -> None:
+    """Check or set the nightly CI gate status."""
+    token = get_ci_token()
+    if "/" not in repo:
+        raise click.ClickException(_("Invalid repo format: {repo}. Expected owner/name.", repo=repo))
+    owner, repo_name = repo.split("/", 1)
+    client = GiteaClient(GITEA_API_URL, token, owner, repo_name)
+
+    if action == "check":
+        status = get_nightly_status(client)
+        if not status:
+            # Bootstrap: no nightly has run yet, allow deploy
+            click.echo("[nightly-gate] No nightly status set — allowing deploy (bootstrap).")
+            if github_output:
+                write_github_output("nightly-gate-passed", "true")
+                write_github_output("nightly-status", "")
+            return
+
+        if status.startswith("passed"):
+            click.echo("[nightly-gate] Nightly passed. Deploy allowed.")
+            if github_output:
+                write_github_output("nightly-gate-passed", "true")
+                write_github_output("nightly-status", status)
+        elif status.startswith("failed"):
+            run_part = status.split(":", 1)[1] if ":" in status else ""
+            run_link = f" (run #{run_part})" if run_part else ""
+            click.echo(
+                _(
+                    "[nightly-gate] Nightly FAILED{run}. Staging deploys are blocked until nightly passes.",
+                    run=run_link,
+                ),
+                err=True,
+            )
+            if github_output:
+                write_github_output("nightly-gate-passed", "false")
+                write_github_output("nightly-status", status)
+            raise click.ClickException(_("Nightly gate failed — staging deploy blocked."))
+        else:
+            click.echo(f"[nightly-gate] Unknown nightly status: {status} — allowing deploy.")
+            if github_output:
+                write_github_output("nightly-gate-passed", "true")
+                write_github_output("nightly-status", status)
+
+    elif action == "set-passed":
+        set_nightly_status(client, f"passed:{run_id}" if run_id else "passed")
+        click.echo(_("[nightly-gate] Set NIGHTLY_STATUS=passed{run}", run=f":{run_id}" if run_id else ""))
+        if github_output:
+            write_github_output("nightly-status", f"passed:{run_id}" if run_id else "passed")
+
+    elif action == "set-failed":
+        set_nightly_status(client, f"failed:{run_id}" if run_id else "failed")
+        click.echo(_("[nightly-gate] Set NIGHTLY_STATUS=failed{run}", run=f":{run_id}" if run_id else ""))
+        if github_output:
+            write_github_output("nightly-status", f"failed:{run_id}" if run_id else "failed")
+
+
+if __name__ == "__main__":  # pragma: no cover
+    cli()

src/devx/ci/pr_review.py

@@ -1,715 +0,0 @@
-#!/usr/bin/env python3
-"""Automated PR review: check architecture compliance, best practices, and quality.
-
-Fetches the PR diff via the Gitea API, runs a series of automated checks,
-and posts a structured review using GiteaClient.create_review.
-
-Checks performed:
-  1. Architecture compliance — no business logic in CLI, no direct subprocess
-     calls outside executor, no hardcoded config that should be in config.py
-  2. Best practices — no bare except, no print() (use click.echo), no TODO/FIXME
-     left in merged code, no functions > 50 lines
-  3. Security — no secrets in code, no shell=True, no eval/exec
-  4. i18n — no raw English strings in click.echo() without _() wrapper
-  5. Resource management — no open() without with statement, no subprocess without cleanup
-  6. Documentation — new CLI commands documented, new modules in architecture.md
-  7. Test coverage — 100% enforced by pytest-cov (checked in quality job)
-  8. Commit conventions — conventional commit format on branch commits
-
-Usage:
-  CI_GITEA_API_TOKEN=<token> [REVIEWER_GITEA_API_TOKEN=<token>] python3 -m devx.ci.pr_review <pr_number> <owner/repo>
-"""
-
-from __future__ import annotations
-
-import os
-import re
-from dataclasses import dataclass, field
-from typing import Any
-
-import click
-from dotenv import load_dotenv  # pyright: ignore[reportMissingImports,reportUnknownVariableType]
-
-from devx.api_clients import GiteaClient
-from devx.config import GITEA_API_URL
-from devx.exceptions import APIError
-from devx.i18n import _
-from devx.tokens import get_ci_token, get_reviewer_token
-
-load_dotenv()
-
-# Files that are exempt from certain checks
-WORKFLOW_ONLY_SUFFIXES = (".yml", ".yaml", ".md", ".json", ".toml", ".cfg", ".ini", ".txt")
-PYTHON_SUFFIX = ".py"
-
-# Architecture rules
-CLI_FILE = "src/devx/cli.py"
-EXECUTOR_FILE = "src/devx/executor.py"
-CONFIG_FILE = "src/devx/config.py"
-
-# Patterns that indicate business logic in CLI (should be in runner_manager.py)
-BUSINESS_LOGIC_IN_CLI = [
-    (r"subprocess\.(run|call|Popen|check_output|check_call)", "subprocess call in CLI — delegate to executor.py"),
-    (r"\bos\.system\b", "os.system call in CLI — delegate to executor.py"),
-    (r"\bansible-playbook\b", "ansible-playbook reference in CLI — delegate to executor.py"),
-]
-
-# Patterns that indicate bad practices
-BAD_PRACTICES = [
-    (r"\bprint\s*\(", "print() found — use click.echo() for user output"),
-    (r"\beval\s*\(", "eval() found — security risk, avoid dynamic code execution"),
-    (r"\bexec\s*\(", "exec() found — security risk, avoid dynamic code execution"),
-    (r"shell\s*=\s*True", "shell=True found — security risk, use shell=False with list args"),
-    (r"except\s*:", "bare except found — catch specific exceptions"),
-    (r"except\s+Exception\s*:", "broad Exception catch — catch specific exceptions"),
-    (r"#\s*(TODO|FIXME|HACK|XXX)", "TODO/FIXME found — resolve before merging"),
-]
-
-# Patterns for hardcoded config values that should be in config.py
-HARDCODED_CONFIG = [
-    (r"https?://[a-z]+\.[a-z]+\.[a-z]+", "hardcoded URL — move to config.py with env var override"),
-]
-
-
-@dataclass
-class ReviewResult:
-    """Result of automated review checks."""
-
-    issues: list[dict[str, Any]] = field(default_factory=list)
-    summary: list[str] = field(default_factory=list)
-
-    @property
-    def has_issues(self) -> bool:
-        return bool(self.issues)
-
-    def add_issue(self, file_path: str, line: int, message: str, severity: str = "warning") -> None:
-        self.issues.append(
-            {
-                "path": file_path,
-                "body": f"[{severity}] {message}",
-                "new_position": line,
-            }
-        )
-
-    def add_summary(self, text: str) -> None:
-        self.summary.append(text)
-
-
-def is_python_file(path: str) -> bool:
-    """Check if a file is a Python source file."""
-    return path.endswith(PYTHON_SUFFIX) and not path.startswith("tests/")
-
-
-def is_workflow_only(path: str) -> bool:
-    """Check if a file is workflow/config/docs only (not Python source)."""
-    return path.endswith(WORKFLOW_ONLY_SUFFIXES) or path.startswith((".gitea/", "docs/", "ansible/"))
-
-
-def check_architecture_compliance(files: list[dict[str, Any]], result: ReviewResult) -> None:
-    """Check that changes follow the documented architecture."""
-    for f in files:
-        path = f.get("filename", "")
-        if not is_python_file(path):
-            continue
-
-        patch = f.get("patch", "")
-        if not patch:
-            continue
-
-        lines = patch.split("\n")
-        current_line = 0
-        for line in lines:
-            if line.startswith("@@"):
-                match = re.search(r"\+(\d+)", line)
-                if match:
-                    current_line = int(match.group(1)) - 1
-                continue
-            if line.startswith("+") and not line.startswith("+++"):
-                current_line += 1
-                content = line[1:]
-
-                # Check for business logic in CLI
-                if path == CLI_FILE:
-                    for pattern, msg in BUSINESS_LOGIC_IN_CLI:
-                        if re.search(pattern, content):
-                            result.add_issue(path, current_line, msg, "error")
-
-    if not result.issues:
-        result.add_summary("- Architecture compliance: OK")
-
-
-def check_best_practices(files: list[dict[str, Any]], result: ReviewResult) -> None:
-    """Check for common code quality issues."""
-    for f in files:
-        path = f.get("filename", "")
-        if not is_python_file(path):
-            continue
-
-        patch = f.get("patch", "")
-        if not patch:
-            continue
-
-        lines = patch.split("\n")
-        current_line = 0
-        for line in lines:
-            if line.startswith("@@"):
-                match = re.search(r"\+(\d+)", line)
-                if match:
-                    current_line = int(match.group(1)) - 1
-                continue
-            if line.startswith("+") and not line.startswith("+++"):
-                current_line += 1
-                content = line[1:]
-
-                for pattern, msg in BAD_PRACTICES:
-                    if re.search(pattern, content):
-                        result.add_issue(path, current_line, msg, "warning")
-
-    if not any(i["body"].startswith("[warning]") for i in result.issues):
-        result.add_summary("- Best practices: OK")
-
-
-def check_security(files: list[dict[str, Any]], result: ReviewResult) -> None:
-    """Check for security issues in changed files."""
-    for f in files:
-        path = f.get("filename", "")
-        if not is_python_file(path):
-            continue
-
-        patch = f.get("patch", "")
-        if not patch:
-            continue
-
-        lines = patch.split("\n")
-        current_line = 0
-        for line in lines:
-            if line.startswith("@@"):
-                match = re.search(r"\+(\d+)", line)
-                if match:
-                    current_line = int(match.group(1)) - 1
-                continue
-            if line.startswith("+") and not line.startswith("+++"):
-                current_line += 1
-                content = line[1:]
-
-                # Check for hardcoded secrets
-                secret_re = r'(token|password|secret|key)\s*=\s*["\'][^"\']{8,}["\']'  # nosec B105
-                is_secret = re.search(secret_re, content, re.IGNORECASE)
-                is_comment = content.strip().startswith("#")
-                is_example = "your-" in content or "example" in content
-                if is_secret and not is_comment and not is_example:
-                    result.add_issue(
-                        path,
-                        current_line,
-                        "potential hardcoded secret — use environment variable",
-                        "error",
-                    )
-
-    if not any(i["body"].startswith("[error]") and "secret" in i["body"] for i in result.issues):
-        result.add_summary("- Security: OK")
-
-
-def check_i18n(files: list[dict[str, Any]], result: ReviewResult) -> None:
-    """Check that user-facing strings are wrapped in _().
-
-    Detects ``click.echo()`` calls with raw string literals that are not
-    wrapped in ``_()``. Only checks ``src/`` files, not tests or scripts.
-    """
-    # Pattern: click.echo("...") or click.echo(f"...") without _() wrapper
-    raw_echo_re = re.compile(r'click\.echo\s*\(\s*["\']([^"\']+)["\']')
-    raw_fstring_re = re.compile(r'click\.echo\s*\(\s*f["\']')
-    # Also check click.ClickException and raise with string
-    raw_exception_re = re.compile(r'click\.ClickException\s*\(\s*["\']([^"\']+)["\']')
-
-    for f in files:
-        path = f.get("filename", "")
-        if not is_python_file(path) or not path.startswith("src/"):
-            continue
-
-        patch = f.get("patch", "")
-        if not patch:
-            continue
-
-        lines = patch.split("\n")
-        current_line = 0
-        for line in lines:
-            if line.startswith("@@"):
-                match = re.search(r"\+(\d+)", line)
-                if match:
-                    current_line = int(match.group(1)) - 1
-                continue
-            if line.startswith("+") and not line.startswith("+++"):
-                current_line += 1
-                content = line[1:]
-
-                # Skip comments and docstrings
-                stripped = content.strip()
-                if stripped.startswith("#") or stripped.startswith('"""') or stripped.startswith("'''"):
-                    continue
-
-                # Check for raw strings in click.echo without _()
-                for regex, msg in [
-                    (raw_echo_re, "click.echo() with raw string — wrap in _() for i18n"),
-                    (raw_fstring_re, "click.echo() with f-string — wrap in _() for i18n"),
-                    (raw_exception_re, "ClickException with raw string — wrap in _() for i18n"),
-                ]:
-                    if regex.search(content):
-                        result.add_issue(path, current_line, msg, "warning")
-
-    if not any("i18n" in i["body"] for i in result.issues):
-        result.add_summary("- i18n: OK")
-
-
-def check_resource_management(files: list[dict[str, Any]], result: ReviewResult) -> None:
-    """Check for resource leaks: open() without with, subprocess without cleanup.
-
-    Detects:
-    - ``open()`` calls not in a ``with`` statement
-    - ``subprocess.Popen()`` without ``.wait()`` or ``.communicate()``
-    """
-    # Pattern: open("...") not preceded by "with" on the same line
-    open_re = re.compile(r"(?<!with\s)\bopen\s*\(")
-    popen_re = re.compile(r"subprocess\.Popen\s*\(")
-
-    for f in files:
-        path = f.get("filename", "")
-        if not is_python_file(path):
-            continue
-
-        patch = f.get("patch", "")
-        if not patch:
-            continue
-
-        lines = patch.split("\n")
-        current_line = 0
-        for line in lines:
-            if line.startswith("@@"):
-                match = re.search(r"\+(\d+)", line)
-                if match:
-                    current_line = int(match.group(1)) - 1
-                continue
-            if line.startswith("+") and not line.startswith("+++"):
-                current_line += 1
-                content = line[1:]
-
-                # Skip comments
-                if content.strip().startswith("#"):
-                    continue
-
-                # Check for open() without with
-                if open_re.search(content) and "with " not in content:
-                    result.add_issue(
-                        path, current_line, "open() without with statement — potential resource leak", "warning"
-                    )
-
-                # Check for Popen without communicate/wait on same line
-                if popen_re.search(content) and ".communicate" not in content and ".wait" not in content:
-                    result.add_issue(
-                        path,
-                        current_line,
-                        "subprocess.Popen() without immediate .communicate() or .wait() — ensure cleanup",
-                        "warning",
-                    )
-
-    if not any("resource" in i["body"].lower() for i in result.issues):
-        result.add_summary("- Resource management: OK")
-
-
-def check_function_length(files: list[dict[str, Any]], result: ReviewResult) -> None:
-    """Check that no new function is excessively long (> 50 lines)."""
-    for f in files:
-        path = f.get("filename", "")
-        if not is_python_file(path):
-            continue
-
-        patch = f.get("patch", "")
-        if not patch:
-            continue
-
-        # Count consecutive added lines within a function
-        lines = patch.split("\n")
-        current_line = 0
-        func_start = 0
-        func_name = ""
-        added_in_func = 0
-
-        for line in lines:
-            if line.startswith("@@"):
-                if func_name and added_in_func > 50:
-                    result.add_issue(
-                        path,
-                        func_start,
-                        f"function '{func_name}' adds {added_in_func} lines — consider splitting (> 50 lines)",
-                        "warning",
-                    )
-                match = re.search(r"\+(\d+)", line)
-                if match:
-                    current_line = int(match.group(1)) - 1
-                func_name = ""
-                added_in_func = 0
-                continue
-            if line.startswith("+") and not line.startswith("+++"):
-                current_line += 1
-                content = line[1:]
-                func_match = re.match(r"\s*def\s+(\w+)\s*\(", content)
-                if func_match:
-                    if func_name and added_in_func > 50:
-                        result.add_issue(
-                            path,
-                            func_start,
-                            f"function '{func_name}' adds {added_in_func} lines — consider splitting (> 50 lines)",
-                            "warning",
-                        )
-                    func_name = func_match.group(1)
-                    func_start = current_line
-                    added_in_func = 0
-                else:
-                    added_in_func += 1
-            elif line.startswith(" ") or line.startswith("-"):
-                pass  # context or removed line
-
-        # Check last function
-        if func_name and added_in_func > 50:
-            result.add_issue(
-                path,
-                func_start,
-                f"function '{func_name}' adds {added_in_func} lines — consider splitting (> 50 lines)",
-                "warning",
-            )
-
-
-def check_documentation(files: list[dict[str, Any]], result: ReviewResult) -> None:
-    """Check that documentation is updated for relevant changes."""
-    has_src_changes = any(
-        is_python_file(f.get("filename", "")) and f.get("filename", "").startswith("src/") for f in files
-    )
-    has_doc_changes = any(
-        f.get("filename", "").startswith("docs/") or f.get("filename", "") in ("README.md", "AGENTS.md", "CHANGELOG.md")
-        for f in files
-    )
-    has_ansible_changes = any(f.get("filename", "").startswith("ansible/") for f in files)
-    has_tofu_changes = any(f.get("filename", "").startswith("tofu/") for f in files)
-    has_workflow_changes = any(f.get("filename", "").startswith(".gitea/") for f in files)
-
-    # Check for TODO/FIXME in changed docs
-    todo_issues: list[str] = []
-    for f in files:
-        filename = f.get("filename", "")
-        if filename.endswith(".md") and filename.startswith(("docs/", "README", "AGENTS")):
-            # Can't check file content from PR API easily, but flag if patch adds TODO
-            patch = f.get("patch", "")
-            if patch and re.search(r"^\+.*\b(TODO|FIXME|HACK|XXX)\b", patch, re.IGNORECASE):
-                todo_issues.append(f"{filename}: new TODO/FIXME added in documentation")
-
-    if has_src_changes and not has_doc_changes:
-        result.add_summary("- Documentation: WARNING — source files changed but no docs updated")
-    elif has_ansible_changes and not has_doc_changes:
-        result.add_summary("- Documentation: WARNING — Ansible role changed but no docs updated")
-    elif has_tofu_changes and not has_doc_changes:
-        result.add_summary("- Documentation: WARNING — OpenTofu changes but no docs updated")
-    elif has_workflow_changes and not has_doc_changes:
-        result.add_summary("- Documentation: INFO — workflow changes (consider updating CI docs if behavior changed)")
-    else:
-        result.add_summary("- Documentation: OK")
-
-    if todo_issues:
-        for issue in todo_issues:
-            result.add_summary(f"- Documentation: WARNING — {issue}")
-
-
-def check_test_coverage(files: list[dict[str, Any]], result: ReviewResult) -> None:
-    """Check that tests are updated for source changes."""
-    has_src_changes = any(
-        is_python_file(f.get("filename", "")) and f.get("filename", "").startswith("src/") for f in files
-    )
-    has_test_changes = any(f.get("filename", "").startswith("tests/") for f in files)
-
-    if has_src_changes and not has_test_changes:
-        result.add_summary("- Tests: WARNING — source files changed but no test files updated")
-    else:
-        result.add_summary("- Tests: OK")
-
-
-def check_commit_conventions(client: GiteaClient, pr_number: str, result: ReviewResult) -> None:
-    """Check that PR commits follow conventional commit format.
-
-    Verifies that at least one commit on the PR branch matches the
-    conventional commit pattern (type: description). Merge commits
-    and revert commits are exempt.
-    """
-    try:
-        commits = client.get_pr_commits(pr_number)
-    except APIError as e:
-        result.add_summary(f"- Commit conventions: ERROR — could not fetch commits: {e.message}")
-        return
-
-    if not commits:
-        result.add_summary("- Commit conventions: OK (no commits to check)")
-        return
-
-    from devx.config import CONVENTIONAL_RE
-
-    has_conventional = False
-    non_conventional: list[str] = []
-
-    for commit in commits:
-        commit_info = commit.get("commit", {})
-        message = str(commit_info.get("message", "") if isinstance(commit_info, dict) else "").split("\n")[0]
-        # Skip merge commits and revert commits
-        if message.startswith(("Merge", "Revert")):
-            continue
-        if CONVENTIONAL_RE.match(message):
-            has_conventional = True
-        else:
-            non_conventional.append(message[:60])
-
-    if has_conventional:
-        result.add_summary("- Commit conventions: OK")
-    elif non_conventional:
-        result.add_summary(
-            f"- Commit conventions: WARNING — no conventional commit found. "
-            f"Non-conventional commits: {', '.join(non_conventional[:3])}"
-        )
-    else:
-        result.add_summary("- Commit conventions: OK (all commits are merges/reverts)")
-
-
-def run_review(client: GiteaClient, pr_number: str) -> ReviewResult:
-    """Run all review checks and return the result."""
-    result = ReviewResult()
-
-    try:
-        files = client.get_pr_files(pr_number)
-    except APIError as e:
-        result.add_summary(f"- ERROR: Could not fetch PR files: {e.message}")
-        return result
-
-    if not files:
-        result.add_summary("- No files changed in this PR")
-        return result
-
-    # Run all checks
-    check_architecture_compliance(files, result)
-    check_best_practices(files, result)
-    check_security(files, result)
-    check_i18n(files, result)
-    check_resource_management(files, result)
-    check_function_length(files, result)
-    check_documentation(files, result)
-    check_test_coverage(files, result)
-    check_commit_conventions(client, pr_number, result)
-
-    return result
-
-
-def build_review_body(result: ReviewResult) -> str:
-    """Build the review body text from the review result."""
-    lines = ["## Automated PR Review", ""]
-
-    for item in result.summary:
-        lines.append(item)
-
-    if result.issues:
-        lines.append("")
-        lines.append(f"**{len(result.issues)} issue(s) found:**")
-        lines.append("")
-        for issue in result.issues:
-            lines.append(f"- `{issue['path']}:{issue['new_position']}` — {issue['body']}")
-    else:
-        lines.append("")
-        lines.append("No issues found by automated checks.")
-
-    lines.append("")
-    lines.append("---")
-    lines.append("**Auto-merge:** If all CI checks pass, this PR will be merged automatically.")
-
-    return "\n".join(lines)
-
-
-def post_review(client: GiteaClient, pr_number: str, result: ReviewResult) -> dict[str, Any]:
-    """Post the review to the PR.
-
-    Uses REQUEST_CHANGES when issues are found, COMMENT otherwise.
-    Never uses APPROVE — the bot shares the PR author's token, so
-    Gitea rejects self-approval. The actual APPROVE must come from
-    the manual review step.
-    """
-    body = build_review_body(result)
-    event = "REQUEST_CHANGES" if result.has_issues else "COMMENT"
-    comments = result.issues if result.has_issues else []
-
-    return client.create_review(pr_number, event=event, body=body, comments=comments)
-
-
-def _post_manual_review(
-    client: GiteaClient,
-    pr_number: str,
-    event: str,
-    body: str | None,
-    checklist_confirmed: bool,
-    checklist_categories: str | None,
-    dry_run: bool,
-    owner: str | None = None,
-    repo_name: str | None = None,
-) -> None:
-    """Post a manual review with validation for APPROVE events.
-
-    When self-approval is rejected (reviewer token belongs to PR author),
-    falls back to the CI token (different user) if available.
-    """
-    if not body or len(body) < 50:
-        raise click.ClickException(_("Review body must be at least 50 characters."))
-
-    if event == "APPROVE":
-        if not checklist_confirmed:
-            raise click.ClickException(
-                _("--checklist-confirmed is required for APPROVE events."),
-            )
-        cats = [c.strip() for c in (checklist_categories or "").split(",") if c.strip()]
-        cat_nums: list[int] = []
-        for c in cats:
-            try:
-                cat_nums.append(int(c))
-            except ValueError:
-                raise click.ClickException(
-                    _("Invalid checklist category: {cat}. Must be numbers.", cat=c),
-                ) from None
-        if len(cat_nums) < 8:
-            raise click.ClickException(
-                _("--checklist-categories must list at least 8 of 13 categories. Got {count}.", count=len(cat_nums)),
-            )
-
-    click.echo(f"Manual review event: {event}")
-    click.echo(f"Body: {body[:80]}...")
-    if checklist_confirmed:
-        click.echo(f"Checklist confirmed: {checklist_categories}")
-
-    if dry_run:
-        click.echo("\n[dry-run] Review not posted.")
-        return
-
-    try:
-        review = client.create_review(pr_number, event=event, body=body)
-    except APIError as e:
-        if "approve" in e.message.lower() or "422" in str(e.status):
-            # Self-approval not allowed (reviewer token belongs to PR author).
-            # Fall back to CI token (different user) if available.
-            ci_token = os.environ.get("CI_GITEA_API_TOKEN", "").strip()
-            if ci_token and owner and repo_name:
-                click.echo(_("Note: Self-approval not allowed with reviewer token. Retrying with CI token."))
-                ci_client = GiteaClient(GITEA_API_URL, ci_token, owner, repo_name)
-                try:
-                    review = ci_client.create_review(pr_number, event=event, body=body)
-                except APIError:
-                    click.echo(_("Note: CI token also cannot approve. Posting COMMENT instead."))
-                    review = client.create_review(pr_number, event="COMMENT", body=body)
-            else:
-                click.echo(_("Note: Self-approval not allowed. Posting COMMENT instead."))
-                review = client.create_review(pr_number, event="COMMENT", body=body)
-        else:
-            raise
-    review_id = review.get("id", "?")
-    click.echo(
-        _(
-            "\nReview #{review_id} posted on PR #{pr_number} with event '{event}'.",
-            review_id=review_id,
-            pr_number=pr_number,
-            event=event,
-        )
-    )
-
-
-@click.command()
-@click.argument("pr_number")
-@click.argument("repo")
-@click.option("--dry-run", is_flag=True, default=False, help="Print review without posting.")
-@click.option(
-    "--event",
-    type=click.Choice(["APPROVE", "REQUEST_CHANGES", "COMMENT"], case_sensitive=False),
-    default=None,
-    help="Post a manual review with the given event (skips automated checks).",
-)
-@click.option("--body", default=None, help="Review body text (required with --event).")
-@click.option(
-    "--checklist-confirmed",
-    is_flag=True,
-    default=False,
-    help="Attest that REVIEW_CHECKLIST.md categories were checked (required for APPROVE).",
-)
-@click.option(
-    "--checklist-categories",
-    default=None,
-    help="Comma-separated checklist category numbers (required for APPROVE, min 8 of 13).",
-)
-def main(
-    pr_number: str,
-    repo: str,
-    dry_run: bool,
-    event: str | None,
-    body: str | None,
-    checklist_confirmed: bool,
-    checklist_categories: str | None,
-) -> None:
-    """Run automated PR review and post results to Gitea.
-
-    Without --event: runs automated checks and posts COMMENT/REQUEST_CHANGES.
-    With --event: posts a manual review (skips automated checks).
-    """
-    try:
-        token = get_reviewer_token() if (event and event.upper() == "APPROVE") else get_ci_token()
-    except click.ClickException:
-        raise click.ClickException(_("ERROR: CI_GITEA_TOKEN is not set.")) from None
-
-    owner, repo_name = repo.split("/")
-    client = GiteaClient(GITEA_API_URL, token, owner, repo_name)
-
-    if event is not None:
-        _post_manual_review(
-            client,
-            pr_number,
-            event.upper(),
-            body,
-            checklist_confirmed,
-            checklist_categories,
-            dry_run,
-            owner=owner,
-            repo_name=repo_name,
-        )
-        return
-
-    result = run_review(client, pr_number)
-
-    body = build_review_body(result)
-    event = "REQUEST_CHANGES" if result.has_issues else "COMMENT"
-
-    click.echo(f"Review event: {event}")
-    click.echo(f"Issues found: {len(result.issues)}")
-    click.echo("")
-    click.echo(body)
-
-    if dry_run:
-        click.echo("\n[dry-run] Review not posted.")
-        return
-
-    try:
-        review = post_review(client, pr_number, result)
-    except APIError as e:
-        if "approve" in e.message.lower() or "422" in str(e.status):
-            click.echo(_("Note: Self-approval not allowed. Posting COMMENT instead."))
-            review = client.create_review(pr_number, event="COMMENT", body=body)
-        else:
-            raise
-    review_id = review.get("id", "?")
-    click.echo(
-        _(
-            "\nReview #{review_id} posted on PR #{pr_number} with event '{event}' ({num_comments} inline comments).",
-            review_id=review_id,
-            pr_number=pr_number,
-            event=event,
-            num_comments=len(result.issues),
-        )
-    )
-
-
-if __name__ == "__main__":  # pragma: no cover
-    main()

src/devx/ci/publish.py

@@ -4,6 +4,10 @@
 Uses git-cliff to generate the release notes from conventional commits.
 Uses the ``tea`` Gitea CLI for release creation.
 
+Gitea release creation is retried up to 3 times with exponential backoff
+(2s, 4s) to handle transient failures (network timeouts, 5xx errors).
+If the release already exists, it is treated as success (idempotent).
+
 Publishing destinations (checked in order):
   1. **Gitea PyPI registry** — if ``--registry-url`` is given (or
      ``DEVX_PYPI_REGISTRY_URL`` env var is set, or ``GITEA_API_URL``
@@ -27,6 +31,7 @@ from pathlib import Path
 
 import click
 from dotenv import load_dotenv  # pyright: ignore[reportMissingImports,reportUnknownVariableType]
+from tenacity import retry, retry_if_exception_type, stop_after_attempt, wait_exponential
 
 from devx.config import GITEA_API_URL, REPO_OWNER
 from devx.gitea_cli import TeaCLI, TeaCLIError, configure_tea_login
@@ -312,13 +317,7 @@ def main(
 
     release_body = generate_release_notes(tag)
 
-    try:
-        tea.create_release(repo, tag=tag, title=tag, body=release_body)
-    except TeaCLIError as e:
-        if "already" in str(e).lower() and "release" in str(e).lower():
-            click.echo(_("Gitea release {tag} already exists — skipping creation.", tag=tag))
-            return
-        raise click.ClickException(_("Release creation failed: {error}", error=str(e))) from None
+    _create_release_with_retry(tea, repo, tag, release_body)
 
     click.echo(
         _(
@@ -328,5 +327,36 @@ def main(
     )
 
 
+def _create_release_with_retry(tea: TeaCLI, repo: str, tag: str, release_body: str) -> None:
+    """Create a Gitea release with retry for transient failures.
+
+    Retries up to 3 times with exponential backoff (2s, 4s) on TeaCLIError
+    unless the error indicates the release already exists (which is treated
+    as success). This handles transient issues like network timeouts, Gitea
+    rate limiting, or temporary 5xx errors that caused CI run #2822 to fail.
+    """
+
+    @retry(
+        stop=stop_after_attempt(3),
+        wait=wait_exponential(multiplier=2, min=2, max=10),
+        retry=retry_if_exception_type(TeaCLIError),
+        reraise=True,
+    )
+    def _attempt() -> None:
+        try:
+            tea.create_release(repo, tag=tag, title=tag, body=release_body)
+        except TeaCLIError as e:
+            error_str = str(e).lower()
+            if "already" in error_str and "release" in error_str:
+                click.echo(_("Gitea release {tag} already exists — skipping creation.", tag=tag))
+                return
+            raise
+
+    try:
+        _attempt()
+    except TeaCLIError as e:
+        raise click.ClickException(_("Release creation failed: {error}", error=str(e))) from None
+
+
 if __name__ == "__main__":  # pragma: no cover
     main()

src/devx/ci/sync_wiki.py

@@ -252,7 +252,7 @@ def commit_and_push(wiki_dir: Path, wiki_url: str, dry_run: bool) -> bool:
 
     # Push
     result = subprocess.run(  # nosec
-        ["git", "push", "--force", wiki_url, "HEAD:master"],
+        ["git", "push", "--force", wiki_url, "HEAD:main"],
         cwd=wiki_dir,
         capture_output=True,
         text=True,

src/devx/ci/validate_commit_msg.py

@@ -118,7 +118,7 @@ def main(commit_msg_file: str | None, branch: str | None, from_git: bool) -> Non
                 "  Expected: <type>: <description>\n"
                 "  Got:      {subject}\n"
                 "  Allowed types: feat, fix, chore, docs, style, refactor,\n"
-                "                 perf, test, ci, build, revert, BREAKING CHANGE",
+                "                 perf, test, ci, build, deps, revert, BREAKING CHANGE",
                 subject=subject,
             )
         )

src/devx/ci/validate_spec.py

@@ -0,0 +1,157 @@
+#!/usr/bin/env python3
+# Implements: REQ-1
+"""Validate that a PR has a spec file with required sections and acceptance criteria.
+
+Spec-driven development gate. Runs in CI before expensive jobs.
+Used by grm, infra, sso-bridge, and devx itself.
+
+Validates:
+1. A spec file exists at ``docs/specs/<TASK-ID>.md`` (TASK-ID extracted from branch).
+2. The spec contains required sections: Problem, Approach, Test Plan, Deploy Plan, Rollback Plan.
+3. The spec contains REQ-ID lines (``REQ-N: <description>``).
+4. The spec contains an Acceptance Criteria checklist with at least one item.
+5. All acceptance criteria checkboxes are checked (``- [x]``).
+
+Usage:
+    python -m devx.ci.validate_spec --branch OBL-INFRA-531-fix-foo
+
+In CI, also pass ``--github-output`` to set ``spec-valid`` and ``spec-path``
+for downstream steps.
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+import click
+from dotenv import load_dotenv
+
+from devx.ci._shared import extract_task_id, write_github_output
+from devx.i18n import _
+
+load_dotenv()
+
+REQUIRED_SECTIONS = [
+    "## Problem",
+    "## Approach",
+    "## Test Plan",
+    "## Deploy Plan",
+    "## Rollback Plan",
+    "## Acceptance Criteria",
+]
+
+REQ_ID_RE = re.compile(r"^REQ-\d+:\s+.+", re.MULTILINE)
+AC_CHECKED_RE = re.compile(r"^\s*- \[x\]\s+.+", re.MULTILINE)
+AC_UNCHECKED_RE = re.compile(r"^\s*- \[ \]\s+.+", re.MULTILINE)
+
+
+def find_spec_file(task_id: str, specs_dir: str = "docs/specs") -> Path | None:
+    """Find the spec file for the given task ID.
+
+    Looks for ``docs/specs/<TASK-ID>.md`` (case-insensitive filename).
+    Returns the Path if found, None otherwise.
+    """
+    base = Path(specs_dir)
+    if not base.is_dir():
+        return None
+    # Exact match (case-insensitive)
+    for p in base.glob("*.md"):
+        if p.stem.upper() == task_id.upper():
+            return p
+    return None
+
+
+def validate_spec_content(content: str) -> list[str]:
+    """Validate spec content and return a list of error messages.
+
+    Returns an empty list if the spec is valid.
+    """
+    errors: list[str] = []
+
+    # Check required sections
+    for section in REQUIRED_SECTIONS:
+        if section not in content:
+            errors.append(_("Missing required section: {section}", section=section))
+
+    # Check for at least one REQ-ID
+    req_ids = REQ_ID_RE.findall(content)
+    if not req_ids:
+        errors.append(_("No REQ-ID lines found. Each requirement must be labeled (e.g., 'REQ-1: <description>')."))
+
+    # Check acceptance criteria has at least one item
+    checked = AC_CHECKED_RE.findall(content)
+    unchecked = AC_UNCHECKED_RE.findall(content)
+    if not checked and not unchecked:
+        errors.append(_("Acceptance Criteria section has no checklist items. Add at least one '- [ ] item'."))
+    elif unchecked:
+        errors.append(
+            _(
+                "Acceptance Criteria has {count} unchecked item(s). All AC items must be checked (- [x]) before merge.",
+                count=len(unchecked),
+            )
+        )
+
+    return errors
+
+
+@click.command()
+@click.option("--branch", required=True, help=_("Branch name (e.g., OBL-INFRA-531-fix-foo)"))
+@click.option("--specs-dir", default="docs/specs", help=_("Directory containing spec files"))
+@click.option(
+    "--github-output",
+    "github_output",
+    is_flag=True,
+    default=False,
+    help=_("Write results to $GITHUB_OUTPUT"),
+)
+@click.option("--allow-missing", is_flag=True, default=False, help=_("Allow missing spec (warn only, don't fail)"))
+def cli(branch: str, specs_dir: str, github_output: bool, allow_missing: bool) -> None:
+    """Validate that a spec file exists and has required content."""
+    task_id = extract_task_id(branch)
+    if not task_id:
+        msg = _("No task ID found in branch name '{branch}'. Expected format: <PREFIX>-N-description.", branch=branch)
+        if allow_missing:
+            click.echo(f"WARNING: {msg}")
+            if github_output:
+                write_github_output("spec-valid", "false")
+                write_github_output("spec-path", "")
+            return
+        raise click.ClickException(msg)
+
+    spec_path = find_spec_file(task_id, specs_dir)
+    if spec_path is None:
+        msg = _(
+            "No spec file found for task {task_id} in {dir}/. Expected: {dir}/{task_id}.md",
+            task_id=task_id,
+            dir=specs_dir,
+        )
+        if allow_missing:
+            click.echo(f"WARNING: {msg}")
+            if github_output:
+                write_github_output("spec-valid", "false")
+                write_github_output("spec-path", "")
+            return
+        raise click.ClickException(msg)
+
+    content = spec_path.read_text(encoding="utf-8")
+    errors = validate_spec_content(content)
+
+    if github_output:
+        write_github_output("spec-valid", "true" if not errors else "false")
+        write_github_output("spec-path", str(spec_path))
+
+    if errors:
+        click.echo("", err=True)
+        click.echo("=" * 60, err=True)
+        click.echo(f"Spec validation FAILED for {spec_path}:", err=True)
+        click.echo("=" * 60, err=True)
+        for e in errors:
+            click.echo(f"  - {e}", err=True)
+        raise click.ClickException(_("Spec validation failed."))
+
+    click.echo(_("[spec-check] Spec validated: {path}", path=spec_path))
+
+
+if __name__ == "__main__":  # pragma: no cover
+    cli()

src/devx/cli.py

@@ -116,13 +116,6 @@ def ci_post_merge(args: tuple[str, ...]) -> None:
     _run_module("devx.ci.post_merge", list(args))
 
 
-@ci.command("pr-review")
-@click.argument("args", nargs=-1)
-def ci_pr_review(args: tuple[str, ...]) -> None:
-    """Run automated PR review."""
-    _run_module("devx.ci.pr_review", list(args))
-
-
 @ci.command("publish")
 @click.argument("args", nargs=-1)
 def ci_publish(args: tuple[str, ...]) -> None:
@@ -172,6 +165,27 @@ def ci_integration_guard(args: tuple[str, ...]) -> None:
     _run_module("devx.ci.integration_guard", list(args))
 
 
+@ci.command("cancel-superseded-runs")
+@click.argument("args", nargs=-1)
+def ci_cancel_superseded_runs(args: tuple[str, ...]) -> None:
+    """Cancel superseded CI runs for the same PR branch."""
+    _run_module("devx.ci.cancel_superseded_runs", list(args))
+
+
+@ci.command("check-workflow-artifact-deps")
+@click.argument("args", nargs=-1)
+def ci_check_workflow_artifact_deps(args: tuple[str, ...]) -> None:
+    """Check that artifact download jobs depend on upload jobs."""
+    _run_module("devx.ci.check_workflow_artifact_deps", list(args))
+
+
+@ci.command("check-workflow-tofu-init")
+@click.argument("args", nargs=-1)
+def ci_check_workflow_tofu_init(args: tuple[str, ...]) -> None:
+    """Check that workflow jobs using tofu state have a tofu-init step."""
+    _run_module("devx.ci.check_workflow_tofu_init", list(args))
+
+
 @cli.group()
 def tools() -> None:
     """Development tool commands."""
@@ -240,6 +254,27 @@ def tools_pr_rebase(args: tuple[str, ...]) -> None:
     _run_module("devx.tools.pr_rebase", list(args))
 
 
+@tools.command("check-docker-init")
+@click.argument("args", nargs=-1)
+def tools_check_docker_init(args: tuple[str, ...]) -> None:
+    """Check that Docker Compose services with healthchecks have init: true."""
+    _run_module("devx.tools.check_docker_init", list(args))
+
+
+@tools.command("check-ansible-set-fact-to-json")
+@click.argument("args", nargs=-1)
+def tools_check_ansible_set_fact_to_json(args: tuple[str, ...]) -> None:
+    """Check that Ansible set_fact tasks don't misuse to_json."""
+    _run_module("devx.tools.check_ansible_set_fact_to_json", list(args))
+
+
+@tools.command("check-alert-rules")
+@click.argument("args", nargs=-1)
+def tools_check_alert_rules(args: tuple[str, ...]) -> None:
+    """Validate rendered Prometheus alert rules with promtool."""
+    _run_module("devx.tools.check_alert_rules", list(args))
+
+
 @cli.group()
 def molecule() -> None:
     """Molecule testing commands (requires devx[molecule])."""
@@ -259,13 +294,6 @@ def molecule_discover_runners(args: tuple[str, ...]) -> None:
     _run_module("devx.molecule.discover_runners", list(args))
 
 
-@molecule.command("guard")
-@click.argument("args", nargs=-1)
-def molecule_guard(args: tuple[str, ...]) -> None:
-    """Run molecule tests sequentially with CI failure polling."""
-    _run_module("devx.molecule.molecule_ci_guard", list(args))
-
-
 @molecule.command("all")
 @click.argument("args", nargs=-1)
 def molecule_all(args: tuple[str, ...]) -> None:

src/devx/config.py

@@ -93,4 +93,4 @@ RETRY_BACKOFF_BASE = 2  # seconds: 2, 4, 8
 RETRY_STATUS_CODES = {429, 500, 502, 503, 504}
 
 # Conventional commit regex — used by validate_commit_msg.py
-CONVENTIONAL_RE = re.compile(r"^(feat|fix|chore|docs|style|refactor|perf|test|ci|build|revert)(\(.+\))?: .+")
+CONVENTIONAL_RE = re.compile(r"^(feat|fix|chore|docs|style|refactor|perf|test|ci|build|revert|deps)(\(.+\))?: .+")

src/devx/gitea_cli.py

@@ -40,27 +40,46 @@ Usage::
 from __future__ import annotations
 
 import json
+import logging
 import shutil
 import subprocess  # nosec B404
 from typing import Any
 
 import click
+from tenacity import (
+    before_sleep_log,
+    retry,
+    retry_if_exception_type,
+    stop_after_attempt,
+    wait_exponential,
+)
 
-from devx.config import GITEA_API_URL
+from devx.config import GITEA_API_URL, MAX_RETRIES, RETRY_BACKOFF_BASE, RETRY_STATUS_CODES
 from devx.i18n import _
 from devx.tokens import get_ci_token
 
+logger = logging.getLogger("gitea_cli")
+
 
 class TeaCLIError(Exception):
     """Raised when a tea CLI command fails."""
 
 
+class _TransientTeaError(TeaCLIError):
+    """Tea CLI error caused by a transient HTTP status (502/503/504/429)."""
+
+
 def configure_tea_login(login_name: str = "devx") -> None:
     """Configure tea CLI login from CI_GITEA_API_TOKEN and DEVX_GITEA_API_URL.
 
     Idempotent: if a login with the same name already exists, it is not re-added.
     Skips silently if tea is not installed or no token is set.
 
+    Raises ``TeaCLIError`` if the login add or default command fails. This is
+    critical because subsequent tea commands (e.g. ``releases create``) will
+    fail with a cryptic "no available login" error if the login was not
+    configured successfully.
+
     Used by CI scripts (publish, notify_failure) that need tea login but
     run in containerized environments where ``make setup`` was not called.
     """
@@ -88,18 +107,31 @@ def configure_tea_login(login_name: str = "devx") -> None:
         return
 
     click.echo(_("Configuring tea login '{name}' for {url}...", name=login_name, url=gitea_url))
-    subprocess.run(  # nosec B603
+    add_result = subprocess.run(  # nosec B603
         [tea_bin, "login", "add", "--name", login_name, "--url", gitea_url, "--token", token],
         capture_output=True,
         text=True,
         check=False,
     )
-    subprocess.run(  # nosec B603
+    if add_result.returncode != 0:
+        raise TeaCLIError(
+            f"tea login add failed (rc={add_result.returncode})\n"
+            f"stdout: {add_result.stdout.strip()}\n"
+            f"stderr: {add_result.stderr.strip()}"
+        )
+
+    default_result = subprocess.run(  # nosec B603
         [tea_bin, "login", "default", login_name],
         capture_output=True,
         text=True,
         check=False,
     )
+    if default_result.returncode != 0:
+        raise TeaCLIError(
+            f"tea login default failed (rc={default_result.returncode})\n"
+            f"stdout: {default_result.stdout.strip()}\n"
+            f"stderr: {default_result.stderr.strip()}"
+        )
 
 
 class TeaCLI:
@@ -122,6 +154,10 @@ class TeaCLI:
     def _run(self, args: list[str], json_output: bool = True) -> str:
         """Run a tea command and return stdout.
 
+        Retries up to ``MAX_RETRIES`` times on transient HTTP errors
+        (502/503/504/429) detected in stderr/stdout, with exponential
+        backoff. Non-transient errors fail immediately.
+
         Args:
             args: Command arguments (without the leading ``tea``).
             json_output: If True, append ``--output json`` to the command.
@@ -130,25 +166,50 @@ class TeaCLI:
             stdout as a string.
 
         Raises:
-            TeaCLIError: If the command fails.
+            TeaCLIError: If the command fails after retries are exhausted.
         """
         cmd = [self._tea, *args]
         if json_output:
             cmd.extend(["--output", "json"])
+
+        def _execute() -> str:
+            try:
+                result = subprocess.run(  # nosec B603
+                    cmd,
+                    capture_output=True,
+                    text=True,
+                    check=False,
+                )
+            except FileNotFoundError as e:
+                raise TeaCLIError(f"tea binary not found ('{self._tea}'). Install tea or add it to PATH.") from e
+            if result.returncode != 0:
+                parts = [
+                    f"tea command failed (rc={result.returncode}): {' '.join(args)}",
+                    f"stdout: {result.stdout.strip()}" if result.stdout.strip() else "",
+                    f"stderr: {result.stderr.strip()}" if result.stderr.strip() else "",
+                ]
+                msg = "\n".join(p for p in parts if p)
+                combined = f"{result.stdout} {result.stderr}".lower()
+                if any(str(code) in combined for code in RETRY_STATUS_CODES):
+                    raise _TransientTeaError(msg)
+                raise TeaCLIError(msg)
+            return result.stdout.strip()
+
+        retry_decorator = retry(
+            stop=stop_after_attempt(MAX_RETRIES),
+            wait=wait_exponential(
+                multiplier=RETRY_BACKOFF_BASE,
+                min=RETRY_BACKOFF_BASE,
+                max=RETRY_BACKOFF_BASE**MAX_RETRIES,
+            ),
+            retry=retry_if_exception_type(_TransientTeaError),
+            before_sleep=before_sleep_log(logger, logging.WARNING),
+            reraise=True,
+        )
         try:
-            result = subprocess.run(  # nosec B603
-                cmd,
-                capture_output=True,
-                text=True,
-                check=False,
-            )
-        except FileNotFoundError as e:
-            raise TeaCLIError(f"tea binary not found ('{self._tea}'). Install tea or add it to PATH.") from e
-        if result.returncode != 0:
-            raise TeaCLIError(
-                f"tea command failed (rc={result.returncode}): {' '.join(args)}\nstderr: {result.stderr.strip()}"
-            )
-        return result.stdout.strip()
+            return retry_decorator(_execute)()
+        except _TransientTeaError as e:
+            raise TeaCLIError(str(e)) from e
 
     def _run_raw(self, args: list[str]) -> str:
         """Run a tea command without JSON output and return stdout."""

src/devx/i18n.py

@@ -6,6 +6,10 @@ Supported: en, bg, de, ru, zh, pl.
 Projects can extend translations by setting DEVX_TRANSLATIONS_PATH to a
 JSON file with additional keys. Keys from the project's file are merged
 on top of devx's built-in translations.
+
+Projects that use different env var names (e.g. GRM_LANG instead of
+DEVX_LANG) can call :func:`configure_i18n` at import time to override
+the defaults.
 """
 
 from __future__ import annotations
@@ -14,15 +18,39 @@ import json
 import os
 from pathlib import Path
 
+# Configurable env var names — projects can override via configure_i18n()
+_lang_env_var = "DEVX_LANG"
+_translations_path_env_var = "DEVX_TRANSLATIONS_PATH"
+
 # Load built-in translations
 _BUILTIN_TRANSLATIONS: dict[str, dict[str, str]] = json.loads(
     (Path(__file__).parent / "translations.json").read_text(encoding="utf-8")
 )
 
 
+def configure_i18n(
+    *,
+    lang_env_var: str = "DEVX_LANG",
+    translations_path_env_var: str = "DEVX_TRANSLATIONS_PATH",
+) -> None:
+    """Override the env var names used for language and translations path.
+
+    This allows downstream projects (e.g. grm) to use their own env var
+    names (e.g. ``GRM_LANG``) while still using devx's i18n system.
+
+    Args:
+        lang_env_var: Environment variable name for language selection.
+        translations_path_env_var: Environment variable name for the
+            path to a JSON file with project-specific translations.
+    """
+    global _lang_env_var, _translations_path_env_var
+    _lang_env_var = lang_env_var
+    _translations_path_env_var = translations_path_env_var
+
+
 def _load_project_translations() -> dict[str, dict[str, str]]:
-    """Load project-specific translations from DEVX_TRANSLATIONS_PATH if set."""
-    path = os.getenv("DEVX_TRANSLATIONS_PATH")
+    """Load project-specific translations from the configured env var if set."""
+    path = os.getenv(_translations_path_env_var)
     if not path:
         return {}
     p = Path(path)
@@ -41,10 +69,11 @@ TRANSLATIONS: dict[str, dict[str, str]] = {**_BUILTIN_TRANSLATIONS, **_load_proj
 def _(key: str, **kwargs: object) -> str:
     """Return a translated string for the given key.
 
-    Translation is opt-in via the ``DEVX_LANG`` environment variable.
-    If unset, English is always returned regardless of system locale.
+    Translation is opt-in via the configured language environment variable
+    (default ``DEVX_LANG``). If unset, English is always returned regardless
+    of system locale.
     """
-    lang = os.getenv("DEVX_LANG", "en")
+    lang = os.getenv(_lang_env_var, "en")
     if lang not in ("en", "bg", "de", "ru", "zh", "pl"):
         lang = "en"
     template = TRANSLATIONS.get(key, {}).get(lang, key)

src/devx/make/devx.mak

@@ -109,7 +109,7 @@ devx-ensure-venv:
 	fi
 
 .PHONY: devx-create-task devx-create-pr devx-push devx-push-with-pr devx-check-config
-.PHONY: devx-pr-status devx-pr-logs devx-pr-label devx-pr-review devx-rebase devx-pr-rebase
+.PHONY: devx-pr-status devx-pr-logs devx-pr-label devx-rebase devx-pr-rebase
 .PHONY: devx-configure-gitea-pypi devx-install-tools devx-install-checkmake devx-checkmake
 .PHONY: devx-workflow-lint devx-workflow-dryrun devx-workflow-dryrun-safe devx-workflow-check
 .PHONY: devx-notify-failure devx-install-hooks devx-activate-scripts devx-venv devx-ensure-venv
@@ -171,16 +171,6 @@ devx-pr-label:
 		$(if $(PR),--pr $(PR)) \
 		--label $(or $(LABEL),ready-to-merge)
 
-# Usage: make devx-pr-review PR=42 EVENT=APPROVE BODY="..." CHECKLIST=1,2,3,4,5,6,7,8,9,10,11,12,13
-#        make devx-pr-review PR=42 EVENT=REQUEST_CHANGES BODY="..."
-#        make devx-pr-review PR=42  (auto review)
-devx-pr-review:
-	@$(DEVX_PYTHON) -m devx.ci.pr_review \
-		$(PR) $(DEVX_REPO_OWNER)/$(DEVX_REPO_NAME) \
-		$(if $(EVENT),--event $(EVENT)) \
-		$(if $(BODY),--body "$(BODY)") \
-		$(if $(CHECKLIST),--checklist-confirmed --checklist-categories $(CHECKLIST))
-
 # Rebase current branch onto origin/master and force-push
 # Usage: make devx-rebase
 #        make devx-rebase NO_PUSH=1
@@ -309,7 +299,7 @@ devx-lint: devx-lint-ruff devx-lint-format devx-typecheck devx-lint-bandit devx-
 # ── Testing ───────────────────────────────────────────────────────────────────
 
 devx-test-unit:
-	@$(DEVX_BIN)/pytest $(DEVX_TEST_PATHS) -q --no-cov
+	@$(DEVX_BIN)/pytest $(DEVX_TEST_PATHS) -q --no-cov -n 8
 
 devx-pytest-cov:
 	@$(DEVX_BIN)/pytest $(DEVX_TEST_PATHS) -n auto --cov=$(DEVX_COV_PKG) --cov-report=term-missing --cov-fail-under=100

src/devx/molecule/distribute_molecule.py

@@ -104,21 +104,36 @@ def discover_scenarios(root: Path | None = None) -> list[str]:
     return sorted(scenarios)
 
 
-def discover_multi_role_scenarios(roles_root: Path | None = None) -> list[tuple[str, str]]:
+def discover_multi_role_scenarios(
+    roles_root: Path | None = None,
+    include_roles: list[str] | None = None,
+    exclude_roles: list[str] | None = None,
+) -> list[tuple[str, str]]:
     """Discover (role, scenario) pairs across all roles under *roles_root*.
 
     Scans ``roles_root/*/molecule/*/`` for scenario directories, skipping
     ``common`` and directories starting with ``_``. Returns a sorted list of
     ``(role_name, scenario_name)`` tuples.
+
+    If *include_roles* is given, only roles whose name is in the list are
+    returned. If *exclude_roles* is given, roles whose name is in the list
+    are skipped. Both filters are case-insensitive.
     """
     if roles_root is None:
         roles_root = DEFAULT_ROLES_ROOT
     if not roles_root.is_dir():
         raise click.ClickException(_("Roles directory not found: {path}", path=str(roles_root)))
+    include_set = {r.lower() for r in include_roles} if include_roles else None
+    exclude_set = {r.lower() for r in exclude_roles} if exclude_roles else None
     pairs: list[tuple[str, str]] = []
     for role_dir in sorted(roles_root.iterdir()):
         if not role_dir.is_dir():
             continue
+        role_name = role_dir.name
+        if include_set is not None and role_name.lower() not in include_set:
+            continue
+        if exclude_set is not None and role_name.lower() in exclude_set:
+            continue
         mol_dir = role_dir / "molecule"
         if not mol_dir.is_dir():
             continue
@@ -348,6 +363,24 @@ def _write_github_env(key: str, value: str) -> None:
     help="JSON file with custom platform list (each entry: name, image, command). "
     "Overrides the default platform matrix. Useful for projects with custom test images.",
 )
+@click.option(
+    "--include-roles",
+    "include_roles",
+    type=str,
+    default=None,
+    help="Comma-separated list of role names to include (multi-role mode only). "
+    "Only scenarios from these roles are distributed. Case-insensitive. "
+    "Example: --include-roles docker_base,crowdsec,disk_cleanup,app_hardening",
+)
+@click.option(
+    "--exclude-roles",
+    "exclude_roles",
+    type=str,
+    default=None,
+    help="Comma-separated list of role names to exclude (multi-role mode only). "
+    "Scenarios from these roles are skipped. Case-insensitive. "
+    "Example: --exclude-roles docker_base,crowdsec,disk_cleanup,app_hardening",
+)
 def cli(
     runner_index: int | None,
     max_runners: int,
@@ -358,11 +391,18 @@ def cli(
     molecule_root: Path | None,
     roles_root: Path | None,
     platforms_file: Path | None,
+    include_roles: str | None,
+    exclude_roles: str | None,
 ) -> None:
     platforms = load_platforms(platforms_file)
+    # Parse role filters
+    include_list = [r.strip() for r in include_roles.split(",")] if include_roles else None
+    exclude_list = [r.strip() for r in exclude_roles.split(",")] if exclude_roles else None
     # Multi-role mode: discover (role, scenario) pairs across all roles
     if roles_root is not None:
-        role_scenarios = discover_multi_role_scenarios(roles_root)
+        role_scenarios = discover_multi_role_scenarios(
+            roles_root, include_roles=include_list, exclude_roles=exclude_list
+        )
         if list_all:
             for role, scenario in role_scenarios:
                 click.echo(f"{role}|{scenario}")

src/devx/molecule/molecule_changed.py

@@ -0,0 +1,158 @@
+"""Detect which Ansible roles changed and output their molecule scenarios.
+
+Usage::
+
+    python -m devx.molecule.molecule_changed --print-targets
+    python -m devx.molecule.molecule_changed --base origin/master --print-roles
+
+Outputs the list of make targets (e.g. molecule-docker-base) for roles
+that have changed files vs the base ref. Used by ``make molecule-changed``
+to run only the molecule scenarios affected by the current diff.
+
+Role-to-target mapping is derived from the directory structure:
+  ansible/roles/<role>/  →  molecule-<role>
+
+For roles with multiple scenarios (e.g. app_container has customer-apps,
+nextcloud, postgres-upgrade, simple-app), the base target runs all
+scenarios for that role.
+
+Playbooks that change also trigger molecule for the roles they include.
+Shared infrastructure changes (ansible.cfg, requirements.yml, molecule/)
+trigger all scenarios.
+"""
+
+from __future__ import annotations
+
+import subprocess  # nosec B404 — used to run git, a trusted binary
+from pathlib import Path
+
+import click
+
+REPO_ROOT = Path.cwd()
+
+# Map role names to make targets.
+ROLE_TARGET_MAP: dict[str, str] = {
+    "app_container": "molecule-app-container",
+    "app_hardening": "molecule-app-hardening",
+    "crowdsec": "molecule-crowdsec",
+    "disk_cleanup": "molecule-disk-cleanup",
+    "docker_base": "molecule-docker-base",
+    "observability": "molecule-observability",
+    "restore": "molecule-restore",
+    "sso_config": "molecule-sso-config",
+    "storage": "molecule-storage",
+    "zitadel": "molecule-zitadel",
+}
+
+# Playbooks that map to molecule scenarios (via roles they include).
+PLAYBOOK_ROLE_MAP: dict[str, list[str]] = {
+    "ansible/playbooks/deploy-observability.yml": ["observability", "docker_base", "zitadel", "crowdsec"],
+    "ansible/playbooks/deploy-customer.yml": ["app_container", "docker_base", "app_hardening", "sso_config"],
+    "ansible/playbooks/configure-oidc.yml": ["sso_config", "app_container"],
+    "ansible/playbooks/prepare-vms.yml": ["docker_base", "app_hardening", "storage", "disk_cleanup", "crowdsec"],
+}
+
+# Shared infrastructure that affects all molecule tests.
+SHARED_PATHS = (
+    "ansible/ansible.cfg",
+    "ansible/requirements.yml",
+    "ansible/molecule/",
+)
+
+# Minimum path parts for a role file: ansible/roles/<role> (3 parts).
+# Files inside the role have more parts, but we only need the role name.
+_MIN_ROLE_PATH_PARTS = 3
+
+
+def _run_git(args: list[str]) -> str:  # pragma: no cover
+    """Run a git command and return stdout."""
+    result = subprocess.run(  # nosec
+        ["git", *args],
+        cwd=REPO_ROOT,
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+    return result.stdout
+
+
+def get_changed_files(base: str) -> list[str]:
+    """Get list of changed files vs base ref."""
+    for ref in [base, "master"]:
+        output = _run_git(["diff", "--name-only", f"{ref}...HEAD"])
+        if output.strip():
+            return sorted(output.strip().splitlines())
+    return []
+
+
+def detect_changed_roles(changed_files: list[str]) -> set[str]:
+    """Detect which roles have changed files."""
+    roles: set[str] = set()
+
+    for filepath in changed_files:
+        # Check if file is in a role directory
+        if filepath.startswith("ansible/roles/"):
+            parts = filepath.split("/")
+            if len(parts) >= _MIN_ROLE_PATH_PARTS:
+                roles.add(parts[2])
+
+        # Check if file is a playbook that maps to roles
+        if filepath in PLAYBOOK_ROLE_MAP:
+            roles.update(PLAYBOOK_ROLE_MAP[filepath])
+
+        # Check shared infrastructure — triggers all roles
+        for shared in SHARED_PATHS:
+            if filepath.startswith(shared):
+                return set(ROLE_TARGET_MAP.keys())
+
+    return roles
+
+
+def roles_to_targets(roles: set[str]) -> list[str]:
+    """Convert role names to make targets."""
+    targets = []
+    for role in sorted(roles):
+        target = ROLE_TARGET_MAP.get(role)
+        if target:
+            targets.append(target)
+    return targets
+
+
+@click.command()
+@click.option(
+    "--base",
+    default="origin/master",
+    help="Base ref to compare against (default: origin/master).",
+)
+@click.option(
+    "--print-targets",
+    is_flag=True,
+    help="Print make targets (e.g. molecule-docker-base).",
+)
+@click.option(
+    "--print-roles",
+    is_flag=True,
+    help="Print role names (default if no --print-targets).",
+)
+def main(base: str, print_targets: bool, print_roles: bool) -> None:
+    """Detect which Ansible roles changed and output molecule scenarios."""
+    changed_files = get_changed_files(base)
+    if not changed_files:
+        click.echo("No changed files detected.", err=True)
+        return
+
+    roles = detect_changed_roles(changed_files)
+    if not roles:
+        click.echo("No molecule scenarios affected by changes.", err=True)
+        return
+
+    if print_targets:
+        for target in roles_to_targets(roles):
+            click.echo(target)
+    else:
+        for role in sorted(roles):
+            click.echo(role)
+
+
+if __name__ == "__main__":  # pragma: no cover
+    main()

src/devx/molecule/molecule_ci_guard.py

@@ -1,284 +0,0 @@
-#!/usr/bin/env python3
-"""Run molecule tests sequentially while polling Gitea for other runner failures.
-
-Each pair is encoded as one of:
-
-- **Single-role (4-part):** ``scenario|platform_name|platform_image|platform_command``
-- **Multi-role (5-part):** ``role|scenario|platform_name|platform_image|platform_command``
-
-Pairs are executed one at a time (molecule scenarios share temp directories and
-Docker networks, so parallel execution within a single runner is unsafe).
-
-A background thread polls the Gitea API. If any other molecule matrix runner
-reports failure, the current molecule subprocess is killed and this runner
-exits early with code 1.
-
-Usage::
-
-    # Single-role
-    python3 -m devx.molecule.molecule_ci_guard pair1 pair2 ...
-    # Multi-role
-    python3 -m devx.molecule.molecule_ci_guard --roles-root ansible/roles pair1 pair2 ...
-
-Environment variables:
-    GITEA_URL           Base URL of the Gitea instance.
-    CI_GITEA_API_TOKEN  API token with repo access (CI_GITEA_TOKEN accepted for legacy).
-    RUN_ID              Workflow run ID (GITHUB_RUN_ID).
-    JOB_NAME            Base job name (GITHUB_JOB), e.g. "molecule-tests".
-    MATRIX_INDEX        Current matrix index (runner-index).
-    GITEA_REPOSITORY    Repository in "owner/repo" format.
-"""
-
-from __future__ import annotations
-
-import contextlib
-import os
-import signal
-import subprocess  # nosec B404
-import sys
-import threading
-import time
-from pathlib import Path
-
-import click
-import requests
-
-from devx.config import REPO_NAME, REPO_OWNER
-from devx.i18n import _
-from devx.tokens import get_ci_token
-
-POLL_INTERVAL = 10
-
-
-def get_running_jobs(gitea_url: str, owner: str, repo: str, token: str, run_id: int) -> list[dict]:
-    """Return jobs for the given workflow run."""
-    url = f"{gitea_url}/api/v1/repos/{owner}/{repo}/actions/runs/{run_id}/jobs"
-    headers = {"Authorization": f"token {token}"}
-    response = requests.get(url, headers=headers, timeout=30)
-    response.raise_for_status()
-    data = response.json()
-    return data.get("jobs", [])
-
-
-def any_other_runner_failed(jobs: list[dict], current_job_name: str, current_index: int) -> bool:
-    """Return True if any other molecule matrix job has failed."""
-    for job in jobs:
-        name = job.get("name", "")
-        if not name.startswith(current_job_name):
-            continue
-        if name == f"{current_job_name} ({current_index})" or name == current_job_name:
-            continue
-        if job.get("conclusion") == "failure":
-            return True
-    return False
-
-
-def poll_for_other_failures(
-    gitea_url: str,
-    owner: str,
-    repo: str,
-    token: str,
-    run_id: int,
-    job_name: str,
-    current_index: int,
-    stop_event: threading.Event,
-    failed_event: threading.Event,
-) -> None:
-    """Background thread: poll API and signal if another runner fails."""
-    while not stop_event.is_set():
-        try:
-            jobs = get_running_jobs(gitea_url, owner, repo, token, run_id)
-            if any_other_runner_failed(jobs, job_name, current_index):
-                click.echo(_("Another molecule runner failed. Stopping this runner early."))
-                failed_event.set()
-                return
-        except requests.RequestException as exc:
-            click.echo(_("API poll warning: {exc}", exc=exc))
-        stop_event.wait(POLL_INTERVAL)
-
-
-def build_molecule_cmd(scenario: str) -> list[str]:
-    """Build the molecule command for a scenario."""
-    cmd = ["molecule", "test"]
-    if scenario != "default":
-        cmd.extend(["-s", scenario])
-    return cmd
-
-
-def parse_pair(pair: str) -> tuple[str, str, str, str, str]:
-    """Parse a pair string into (role, scenario, platform_name, platform_image, platform_command).
-
-    Supports both 4-part (single-role) and 5-part (multi-role) formats.
-    For 4-part pairs, role is empty (caller uses default role dir).
-    Spaces in the command field are encoded as ``__SPACE__`` to survive
-    shell word-splitting when ``$TEST_PAIRS`` is expanded unquoted.
-    """
-    parts = pair.split("|")
-    if len(parts) == 4:
-        return "", parts[0], parts[1], parts[2], parts[3].replace("__SPACE__", " ")
-    if len(parts) == 5:
-        return parts[0], parts[1], parts[2], parts[3], parts[4].replace("__SPACE__", " ")
-    raise click.ClickException(f"Invalid pair format: {pair!r} (expected 4 or 5 pipe-delimited parts)")
-
-
-def build_env_for_pair(pair: str, base_env: dict[str, str]) -> dict[str, str]:
-    """Build environment for a single molecule pair."""
-    _role, _scenario, platform_name, platform_image, platform_command = parse_pair(pair)
-    env = base_env.copy()
-    env["MOLECULE_PLATFORM_NAME"] = platform_name
-    env["MOLECULE_PLATFORM_IMAGE"] = platform_image
-    if platform_command:
-        env["MOLECULE_PLATFORM_COMMAND"] = platform_command
-    elif "MOLECULE_PLATFORM_COMMAND" in env:
-        del env["MOLECULE_PLATFORM_COMMAND"]
-    env["ANSIBLE_ALLOW_BROKEN_CONDITIONALS"] = "true"
-    # Use a fresh MOLECULE_HOME per pair to avoid stale config cache
-    # from previous CI runs (causes "Instances missing" errors).
-    if "MOLECULE_HOME" not in env:
-        import tempfile
-
-        env["MOLECULE_HOME"] = tempfile.mkdtemp(prefix="molecule-ci-")
-    return env
-
-
-def resolve_role_dir(role: str, roles_root: Path | None, repo_root: Path) -> Path:
-    """Resolve the working directory for a molecule pair.
-
-    For multi-role pairs (role non-empty), uses ``roles_root/role``.
-    For single-role pairs, auto-discovers the first role with a molecule/
-    subdirectory under ``repo_root/ansible/roles/``.
-    """
-    if role:
-        if roles_root is None:
-            roles_root = repo_root / "ansible" / "roles"
-        return roles_root / role
-    roles_dir = repo_root / "ansible" / "roles"
-    if roles_dir.is_dir():
-        role_dirs = sorted(d for d in roles_dir.iterdir() if (d / "molecule").is_dir())
-        if role_dirs:
-            return role_dirs[0]
-    return roles_dir / "role"  # will produce a clear "not found" error
-
-
-@click.command()
-@click.argument("pairs", nargs=-1, required=True)
-@click.option(
-    "--roles-root",
-    type=click.Path(exists=True, file_okay=False, path_type=Path),
-    default=None,
-    help="Root directory for multi-role pairs (e.g. ansible/roles). Required when pairs use 5-part format.",
-)
-def cli(pairs: tuple[str, ...], roles_root: Path | None) -> None:
-    """Run molecule pairs sequentially, stop if another CI runner fails."""
-    gitea_url = os.environ.get("GITEA_URL", "")
-    try:
-        token = get_ci_token()
-    except click.ClickException:
-        token = None
-    run_id = int(os.environ.get("RUN_ID", "0"))
-    job_name = os.environ.get("JOB_NAME", "molecule-tests")
-    current_index = int(os.environ.get("MATRIX_INDEX", "0"))
-    repository = os.environ.get("GITEA_REPOSITORY", "")
-    owner, _sep, repo = repository.partition("/")
-    if not owner or not repo:
-        owner, repo = REPO_OWNER, REPO_NAME
-
-    if not all([gitea_url, token, run_id]):
-        click.echo(_("GITEA_URL/CI_GITEA_TOKEN/RUN_ID not set; running without cross-runner cancellation."))
-
-    # When devx is installed as a pip package, __file__ resolves to the
-    # site-packages directory, not the repo root. Use GITHUB_WORKSPACE
-    # (set by Gitea Actions) or cwd as the repo root.
-    repo_root = Path(os.environ.get("GITHUB_WORKSPACE", os.getcwd())).resolve()
-
-    base_env = os.environ.copy()
-    base_env.setdefault("DOCKER_HOST", f"unix:///run/user/{os.getuid()}/docker.sock")
-    base_env.setdefault("ANSIBLE_INJECT_INVOCATION", "1")
-
-    stop_event = threading.Event()
-    failed_event = threading.Event()
-
-    if gitea_url and token and run_id:
-        poller = threading.Thread(
-            target=poll_for_other_failures,
-            args=(
-                gitea_url,
-                owner,
-                repo,
-                token,
-                run_id,
-                job_name,
-                current_index,
-                stop_event,
-                failed_event,
-            ),
-            daemon=True,
-        )
-        poller.start()
-
-    try:
-        for pair in pairs:
-            if failed_event.is_set():
-                sys.exit(1)
-
-            role, scenario, platform_name, _img, _cmd = parse_pair(pair)
-            click.echo(_("Running: {scenario} on {platform}", scenario=scenario, platform=platform_name))
-
-            cmd = build_molecule_cmd(scenario)
-            env = build_env_for_pair(pair, base_env)
-            cwd = resolve_role_dir(role, roles_root, repo_root)
-
-            process = subprocess.Popen(  # nosec B603
-                cmd,
-                cwd=str(cwd),
-                env=env,
-                preexec_fn=os.setsid,
-            )
-
-            try:
-                while process.poll() is None:
-                    if failed_event.is_set():
-                        with contextlib.suppress(ProcessLookupError):
-                            os.killpg(os.getpgid(process.pid), signal.SIGTERM)
-                        try:
-                            process.wait(timeout=10)
-                        except subprocess.TimeoutExpired:
-                            with contextlib.suppress(ProcessLookupError):
-                                os.killpg(os.getpgid(process.pid), signal.SIGKILL)
-                            process.wait()
-                        sys.exit(1)
-                    time.sleep(1)
-            except KeyboardInterrupt:
-                with contextlib.suppress(ProcessLookupError):
-                    os.killpg(os.getpgid(process.pid), signal.SIGTERM)
-                process.wait()
-                sys.exit(1)
-
-            rc = process.returncode
-
-            if rc != 0:
-                click.echo(_("FAILED: {pair} exited with code {code}", pair=pair, code=rc))
-                sys.exit(rc)
-
-            click.echo(_("PASSED: {pair}", pair=pair))
-
-            # Prune Docker data between scenarios to prevent disk exhaustion
-            # in Docker-in-Docker molecule containers (each scenario pulls
-            # hundreds of MB of images that accumulate across pairs).
-            with contextlib.suppress(subprocess.SubprocessError, OSError):
-                subprocess.run(  # nosec B603, B607
-                    ["docker", "system", "prune", "-af", "--volumes"],
-                    check=False,
-                    capture_output=True,
-                    timeout=60,
-                )
-
-        click.echo(_("All molecule tests passed."))
-    finally:
-        stop_event.set()
-
-    sys.exit(0)
-
-
-if __name__ == "__main__":  # pragma: no cover
-    cli()

src/devx/molecule/start_docker.py

@@ -10,6 +10,12 @@ If the host socket is not available, it tries the rootless socket, then
 starts a local ``dockerd`` with the vfs storage driver (requires
 privileged container).
 
+When the host socket IS available but has limited disk space (e.g. an
+inner DinD daemon writing to a 38 GB container overlay), the script
+prefers a rootless socket that has more available space.  This prevents
+"no space left on device" errors during molecule tests that pull images
+and create containers via the Docker daemon.
+
 Usage::
 
     python3 -m devx.molecule.start_docker [--timeout 30]
@@ -17,8 +23,10 @@ Usage::
 
 from __future__ import annotations
 
+import contextlib
 import glob
 import os
+import shutil
 import subprocess  # nosec B404
 import sys
 import tempfile
@@ -32,6 +40,16 @@ DEFAULT_TIMEOUT = 30
 DOCKER_SOCK = "/var/run/docker.sock"
 # Rootless socket fallback (e.g. /run/user/994/docker.sock)
 ROOTLESS_SOCK = f"/run/user/{os.getuid()}/docker.sock"
+# Host Docker socket mounted by gitea_runner config (see runner config
+# ``options: "-v /run/user/<uid>/docker.sock:/run/host-docker.sock"``).
+# This gives CI containers access to the host's rootless Docker daemon,
+# which has the full host filesystem (e.g. 455 GB) instead of the
+# container's limited overlay (e.g. 38 GB).
+HOST_DOCKER_SOCK = "/run/host-docker.sock"
+# Minimum free bytes for a Docker daemon to be considered usable.
+# Below this, image pulls and container creation will fail with ENOSPC.
+# 20 GB leaves room for molecule-test-base (~500 MB) + a few containers.
+MIN_FREE_BYTES = 20 * 1024**3  # 20 GB
 
 
 def is_docker_ready() -> bool:
@@ -46,6 +64,46 @@ def is_docker_ready() -> bool:
     return result.returncode == 0
 
 
+def _get_docker_free_bytes() -> int:
+    """Get free disk space (bytes) at the Docker daemon's data root.
+
+    Returns 0 if the daemon is not reachable or the data root cannot be
+    determined.
+    """
+    docker_host = os.environ.get("DOCKER_HOST", f"unix://{DOCKER_SOCK}")
+    try:
+        result = subprocess.run(  # nosec B603 B607
+            [
+                "docker",
+                "info",
+                "--format",
+                "{{.DockerRootDir}}",
+            ],
+            capture_output=True,
+            text=True,
+            timeout=10,
+            check=False,
+            env={**os.environ, "DOCKER_HOST": docker_host},
+        )
+        if result.returncode != 0 or not result.stdout.strip():
+            return 0
+        data_root = result.stdout.strip()
+        if not os.path.exists(data_root):
+            return 0
+        return shutil.disk_usage(data_root).free
+    except (FileNotFoundError, subprocess.TimeoutExpired, OSError):
+        return 0
+
+
+def _try_socket(sock_path: str) -> bool:
+    """Set DOCKER_HOST to *sock_path* and check if the daemon is ready.
+
+    Returns ``True`` if the daemon responds, ``False`` otherwise.
+    """
+    os.environ["DOCKER_HOST"] = f"unix://{sock_path}"
+    return is_docker_ready()
+
+
 def _diagnose_socket() -> None:
     """Print diagnostic info about the Docker socket."""
     click.echo(f"DOCKER_HOST = {os.environ.get('DOCKER_HOST', '(not set)')}")
@@ -97,50 +155,177 @@ def _diagnose_socket() -> None:
 def start_docker_daemon(timeout: int = DEFAULT_TIMEOUT) -> bool:
     """Ensure Docker is ready for molecule tests.
 
-    First tries the host socket. If that works, sets ``DOCKER_HOST`` and
-    returns immediately. If not, tries the rootless socket. If neither
-    works, starts a local ``dockerd`` with vfs storage driver (requires
-    privileged container).
+    Tries sockets in this order, preferring ones with enough disk space:
+
+    1. Host rootless socket (``/run/host-docker.sock``) — mounted by the
+       gitea runner config, has access to the host's full filesystem
+       (e.g. 455 GB).  Preferred over the inner dockerd.
+    2. Default socket (``/var/run/docker.sock``) — may be an inner dockerd
+       started by the CI image (v29.5.3) with data root on the container's
+       limited overlay (e.g. 38 GB, often 100 % full).
+    3. Other rootless sockets (``/run/user/*/docker.sock``).
+    4. Local ``dockerd`` with vfs storage driver — last resort.
 
     Returns ``True`` if Docker is ready, ``False`` if it failed to
     start within the timeout.
     """
-    # Point Docker CLI and Python library to the socket explicitly
-    os.environ["DOCKER_HOST"] = f"unix://{DOCKER_SOCK}"
-
     # Diagnose socket state
     click.echo("--- Docker socket diagnostics ---")
     _diagnose_socket()
     click.echo("--- End diagnostics ---")
 
-    # Check if host Docker is already available
-    if is_docker_ready():
-        click.echo(_("Docker daemon already running"))
-        return True
-
-    # Try rootless socket (e.g. /run/user/994/docker.sock)
-    click.echo(f"Trying rootless socket: {ROOTLESS_SOCK}")
-    os.environ["DOCKER_HOST"] = f"unix://{ROOTLESS_SOCK}"
-    if os.path.exists(ROOTLESS_SOCK) and is_docker_ready():
-        click.echo(_("Docker daemon already running"))
-        return True
-
-    # Scan for any rootless sockets at other UIDs
+    # Collect candidate sockets in priority order.
+    # The host's rootless Docker socket (mounted at /run/host-docker.sock
+    # by the gitea runner config) is preferred — it has access to the
+    # host's full filesystem instead of the container's limited overlay.
+    candidates: list[str] = []
+    if os.path.exists(HOST_DOCKER_SOCK):
+        candidates.append(HOST_DOCKER_SOCK)
+    if os.path.exists(DOCKER_SOCK):
+        candidates.append(DOCKER_SOCK)
+    if os.path.exists(ROOTLESS_SOCK):
+        candidates.append(ROOTLESS_SOCK)
     for sock in sorted(glob.glob("/run/user/*/docker.sock")):
-        if sock == ROOTLESS_SOCK:
+        if sock not in candidates:
+            candidates.append(sock)
+
+    # Try each candidate socket — prefer one with enough free space
+    for sock in candidates:
+        click.echo(f"Trying socket: {sock}")
+        if not _try_socket(sock):
             continue
-        click.echo(f"Trying alternative rootless socket: {sock}")
-        os.environ["DOCKER_HOST"] = f"unix://{sock}"
-        if is_docker_ready():
+        free_bytes = _get_docker_free_bytes()
+        free_gb = free_bytes / 1024**3
+        click.echo(f"  Docker daemon ready (free space: {free_gb:.1f} GB)")
+        if free_bytes >= MIN_FREE_BYTES:
             click.echo(_("Docker daemon already running"))
             return True
+        # If free_bytes is 0, the Docker root dir is on the host filesystem
+        # (not accessible from inside the container). This is expected for
+        # the host's rootless Docker — it has the full host disk.
+        # Only trust this for /run/host-docker.sock (known host socket).
+        # For other sockets (e.g. inner dockerd), free_bytes == 0 means
+        # the data root path doesn't exist inside the container — the
+        # inner dockerd may be using the container's full overlay.
+        if free_bytes == 0 and sock == HOST_DOCKER_SOCK:
+            click.echo("Host rootless Docker root dir not accessible from container, using it")
+            return True
+        # If free_bytes is 0 and there are no dockerd processes inside the
+        # container, the socket is the host's Docker (mounted from outside).
+        # The data root is on the host filesystem and has plenty of space.
+        if free_bytes == 0 and sock == DOCKER_SOCK:
+            has_inner_dockerd = False
+            with contextlib.suppress(Exception):
+                pgrep_result = subprocess.run(  # nosec B603 B607
+                    ["pgrep", "-f", "dockerd"],
+                    capture_output=True,
+                    text=True,
+                    timeout=5,
+                )
+                has_inner_dockerd = pgrep_result.returncode == 0
+            if not has_inner_dockerd:
+                click.echo("No inner dockerd found, socket is host Docker (data root on host), using it")
+                return True
+        click.echo(f"  Insufficient space ({free_gb:.1f} GB), trying next...")
 
+    # No socket with sufficient space found.
+    # Don't fall back to the low-space inner dockerd — it will fail
+    # on image pulls.  Instead, kill the inner dockerd, clean up its
+    # data root to free space, and start a new dockerd using the
+    # freed space on the container's overlay.
     click.echo(_("Host Docker not available, starting local dockerd..."))
 
-    # Reset DOCKER_HOST to host socket for local dockerd
-    os.environ["DOCKER_HOST"] = f"unix://{DOCKER_SOCK}"
+    # Kill the inner dockerd (started by the CI image) to free its
+    # data root and socket.  The inner dockerd uses the container's
+    # overlay (38G, often 100% full).  Killing it frees up the
+    # socket and any space used by its containers/volumes.
+    # Use SIGKILL (-9) since the inner dockerd may not respond to SIGTERM.
+    # Try multiple approaches to ensure the inner dockerd is killed.
+    with contextlib.suppress(Exception):
+        result = subprocess.run(  # nosec B603 B607
+            ["pgrep", "-af", "dockerd"],
+            capture_output=True,
+            text=True,
+            timeout=5,
+        )
+        if result.stdout.strip():
+            click.echo(f"  dockerd processes before kill: {result.stdout.strip()}")
+
+    for pattern in ["dockerd", "dockerd-entrypoint.sh", "containerd"]:
+        with contextlib.suppress(Exception):
+            subprocess.run(  # nosec B603 B607
+                ["pkill", "-9", "-f", pattern],
+                check=False,
+                timeout=5,
+            )
+    time.sleep(3)
+
+    # Check if dockerd processes are still alive
+    with contextlib.suppress(Exception):
+        result = subprocess.run(  # nosec B603 B607
+            ["pgrep", "-af", "dockerd"],
+            capture_output=True,
+            text=True,
+            timeout=5,
+        )
+        if result.stdout.strip():
+            click.echo(f"  dockerd processes after kill: {result.stdout.strip()}")
+            # Try killing by PID directly
+            for pid_str in result.stdout.split("\n"):
+                pid = pid_str.split()[0] if pid_str.strip() else ""
+                if pid:
+                    with contextlib.suppress(Exception):
+                        os.kill(int(pid), 9)
+            time.sleep(2)
+
+    # Verify the inner dockerd is actually dead.  If we can still
+    # connect to /var/run/docker.sock, the old daemon is still running
+    # and we need to use a different socket path.
+    old_daemon_alive = False
+    with contextlib.suppress(Exception):
+        result = subprocess.run(  # nosec B603 B607
+            ["docker", "info"],
+            env={**os.environ, "DOCKER_HOST": f"unix://{DOCKER_SOCK}"},
+            capture_output=True,
+            timeout=5,
+        )
+        old_daemon_alive = result.returncode == 0
+
+    if old_daemon_alive:
+        click.echo("  Inner dockerd still alive, using alternate socket")
+        local_sock = "/dev/shm/docker.sock"  # nosec B108
+    else:
+        local_sock = DOCKER_SOCK
+
+    # Clean up the inner dockerd's data root to free space.
+    # The inner dockerd stores images, containers, and volumes here.
+    # Removing them frees up ~2.4GB on the container's overlay.
+    inner_data_root = "/home/grm-ci-runner-*/.local/share/docker"
+    rm_paths = " ".join(f"{inner_data_root}/{d}" for d in ("overlay2", "image", "volumes", "containers"))
+    with contextlib.suppress(Exception):
+        subprocess.run(  # nosec B603 B607
+            ["sh", "-c", f"rm -rf {rm_paths}"],
+            check=False,
+            timeout=30,
+        )
+
+    # Use a fresh data root.  If the inner dockerd is dead, use the
+    # container's overlay (38G, with freed space).  If the inner
+    # dockerd is still alive, use /dev/shm (16G tmpfs) — the overlay
+    # is still full because the inner dockerd's data can't be cleaned.
+    docker_data_root = "/dev/shm/docker" if old_daemon_alive else "/tmp/docker-data"  # nosec B108
+
+    # Remove stale socket if present
+    with contextlib.suppress(OSError):
+        os.unlink(local_sock)
+
+    os.environ["DOCKER_HOST"] = f"unix://{local_sock}"
 
     # Start local dockerd (requires privileged container)
+    # Use /tmp/docker-data as data root on the container's overlay.
+    # The inner dockerd's data root has been cleaned up, freeing ~2.4GB.
+    # vfs storage driver is used since overlay2 may not work inside
+    # a Docker-in-Docker container without --privileged.
     log_file = tempfile.NamedTemporaryFile(  # noqa: SIM115
         mode="w", suffix="dockerd.log", delete=False
     )
@@ -150,8 +335,13 @@ def start_docker_daemon(timeout: int = DEFAULT_TIMEOUT) -> bool:
             "dockerd",
             "--storage-driver",
             "vfs",
+            "--data-root",
+            docker_data_root,
+            "--iptables=false",
+            "--ip6tables=false",
+            "--bridge=none",
             "-H",
-            f"unix://{DOCKER_SOCK}",
+            f"unix://{local_sock}",
         ],
         stdout=log_file,
         stderr=subprocess.STDOUT,

src/devx/tokens.py

@@ -2,19 +2,16 @@
 
 Centralizes Gitea/Vikunja token discovery with role-based environment
 variable names and backwards compatibility with the legacy
-``CI_GITEA_TOKEN`` / ``REVIEW_GITEA_TOKEN`` naming convention.
+``CI_GITEA_TOKEN`` naming convention.
 
 Roles:
 - ``CI_GITEA_API_TOKEN``: CI workflows (read actions, post status, merge, etc.)
-- ``REVIEWER_GITEA_API_TOKEN``: PR approval reviews (must be a different user
-  from the PR author for Gitea to accept the review as an approval)
 - ``DEVELOPER_GITEA_API_TOKEN``: local development tools (create-task,
   create-pr, setup, etc.)
 
 Fallbacks:
 - New role names are checked first.
-- Legacy names (``CI_GITEA_TOKEN``, ``REVIEW_GITEA_TOKEN``) are accepted for
-  backwards compatibility.
+- Legacy names (``CI_GITEA_TOKEN``) are accepted for backwards compatibility.
 - If no role-specific token is set, the generic CI tokens are tried last.
 """
 
@@ -28,12 +25,6 @@ from devx.i18n import _
 
 # Token environment variable names, in lookup priority order.
 CI_TOKEN_NAMES = ["CI_GITEA_API_TOKEN", "CI_GITEA_TOKEN"]
-REVIEWER_TOKEN_NAMES = [
-    "REVIEWER_GITEA_API_TOKEN",
-    # Legacy name used before role-based tokens.
-    "REVIEW_GITEA_TOKEN",
-    *CI_TOKEN_NAMES,
-]
 DEVELOPER_TOKEN_NAMES = ["DEVELOPER_GITEA_API_TOKEN", *CI_TOKEN_NAMES]
 
 VIKUNJA_TOKEN_NAMES = ["VIKUNJA_TOKEN"]
@@ -61,11 +52,6 @@ def get_ci_token() -> str:
     return get_token(*CI_TOKEN_NAMES)
 
 
-def get_reviewer_token() -> str:
-    """Resolve the reviewer Gitea API token used for PR approvals."""
-    return get_token(*REVIEWER_TOKEN_NAMES)
-
-
 def get_developer_token() -> str:
     """Resolve the developer Gitea API token used for local tooling."""
     return get_token(*DEVELOPER_TOKEN_NAMES)

src/devx/tools/build_image.py

@@ -40,13 +40,17 @@ and ``CI_GITEA_USERNAME`` environment variables, matching the existing CI workfl
 
 from __future__ import annotations
 
+import base64
 import json
 import os
 import subprocess  # nosec B404
+import urllib.error
+import urllib.request
 from dataclasses import dataclass, field
 from pathlib import Path
 
 import click
+from tenacity import retry, retry_if_exception_type, stop_after_attempt, wait_exponential
 
 from devx.i18n import _
 from devx.tokens import get_developer_token
@@ -174,9 +178,12 @@ def build_image(
         return True
 
     click.echo(f"Building {spec.name} ({len(full_tags)} tag(s))...")
+    # Use legacy builder (DOCKER_BUILDKIT=0) to avoid OCI-format manifest
+    # blobs (attestation, config) that the Gitea registry rejects with 403.
     result = subprocess.run(  # nosec B603
         cmd,
         check=False,
+        env={**os.environ, "DOCKER_BUILDKIT": "0"},
     )
     if result.returncode != 0:
         click.echo(_("Build failed for {name}", name=spec.name), err=True)
@@ -185,38 +192,188 @@ def build_image(
     return True
 
 
+def delete_remote_manifest(
+    registry: str,
+    name: str,
+    tag: str,
+    username: str,
+    token: str,
+    *,
+    dry_run: bool = False,
+) -> bool:
+    """Delete an existing manifest from the Gitea container registry.
+
+    Gitea 1.27 has a bug (#31964) where pushing a tag that already exists
+    fails with HTTP 500 "package version already exists".  This function
+    deletes the existing manifest before the push to work around it.
+
+    Returns True if deleted or not found, False on unexpected errors.
+    """
+    manifest_url = f"https://{registry}/v2/{name}/manifests/{tag}"
+    if dry_run:
+        click.echo(f"[dry-run] DELETE {manifest_url}")
+        return True
+
+    # First, get the digest via HEAD
+    req = urllib.request.Request(manifest_url, method="HEAD")  # nosec B310
+    auth_str = f"{username}:{token}"
+    req.add_header("Authorization", f"Basic {base64.b64encode(auth_str.encode()).decode()}")
+    req.add_header("Accept", "application/vnd.docker.distribution.manifest.v2+json")
+    try:
+        with urllib.request.urlopen(req, timeout=30) as resp:  # nosec B310
+            digest = resp.headers.get("Docker-Content-Digest")
+    except urllib.error.HTTPError as e:
+        if e.code == 404:
+            return True  # Tag doesn't exist — nothing to delete
+        if e.code == 405:
+            # HEAD not supported — try GET with a range
+            pass
+        else:
+            click.echo(f"  Warning: HEAD {tag} returned {e.code}", err=True)
+            return True  # Don't block the push
+    except urllib.error.URLError as e:
+        click.echo(f"  Warning: HEAD {tag} failed: {e}", err=True)
+        return True  # Don't block the push
+    else:
+        if not digest:
+            return True
+        # Delete by digest
+        del_url = f"https://{registry}/v2/{name}/manifests/{digest}"
+        del_req = urllib.request.Request(del_url, method="DELETE")  # nosec B310
+        del_req.add_header("Authorization", f"Basic {base64.b64encode(auth_str.encode()).decode()}")
+        try:
+            with urllib.request.urlopen(del_req, timeout=30) as resp:  # nosec B310
+                click.echo(f"  Deleted existing {tag} (digest: {digest[:19]}...)")
+        except urllib.error.HTTPError as e:
+            if e.code == 404:
+                return True  # Already gone
+            click.echo(f"  Warning: DELETE {tag} returned {e.code}", err=True)
+            return True  # Don't block the push
+        except urllib.error.URLError as e:
+            click.echo(f"  Warning: DELETE {tag} failed: {e}", err=True)
+            return True
+    return True
+
+
+class PushHTTP500Error(Exception):
+    """Raised when docker push fails with an HTTP 500 from the registry."""
+
+
+def _run_push(cmd: list[str]) -> subprocess.CompletedProcess[str]:
+    """Run a docker push command, raising PushHTTP500Error on registry 500.
+
+    The Gitea container registry (v1.27.x) has a race condition in
+    BlobUploader.Append that causes intermittent HTTP 500 "offset
+    mismatch" errors during concurrent blob uploads.  Retrying the
+    push gives the registry time to recover.
+
+    Docker sends push progress/errors to both stdout and stderr depending
+    on the error type, so both streams are checked for the 500 status.
+    Uses stderr=STDOUT to merge both streams into stdout, ensuring all
+    output is captured in one place (docker push output behavior varies
+    depending on TTY detection).
+    """
+    result = subprocess.run(  # nosec B603
+        cmd,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.STDOUT,
+        text=True,
+        check=False,
+    )
+    if result.returncode != 0 and "500" in (result.stdout or ""):
+        raise PushHTTP500Error(result.stdout.strip())
+    return result
+
+
 def push_image(
     spec: ImageSpec,
     registry: str,
     *,
     dry_run: bool = False,
+    username: str = "",
+    token: str = "",
 ) -> bool:
     """Push all tags of a Docker image to the registry.
 
     Returns True if all pushes succeed, False if any fail.
+
+    Push-first strategy: try pushing directly.  Only if the push fails
+    with Gitea #31964 ("package version already exists") do we delete
+    the old manifest and retry.  This avoids losing the existing tag
+    when the push fails for unrelated reasons (e.g. HTTP 500).
+
+    HTTP 500 errors from the Gitea registry race condition are retried
+    up to 3 times with exponential backoff (5s, 10s) via tenacity.
     """
     full_tags = [build_full_tag(registry, spec.name, t) for t in spec.tags]
     all_ok = True
-    for ft in full_tags:
+    for ft, tag in zip(full_tags, spec.tags, strict=False):
         cmd = ["docker", "push", ft]
         if dry_run:
             click.echo(f"[dry-run] {' '.join(cmd)}")
             continue
         click.echo(f"Pushing {ft}...")
-        result = subprocess.run(  # nosec B603
-            cmd,
-            capture_output=True,
-            text=True,
-            check=False,
+
+        @retry(
+            stop=stop_after_attempt(5),
+            wait=wait_exponential(multiplier=10, min=10, max=60),
+            retry=retry_if_exception_type(PushHTTP500Error),
+            before_sleep=lambda retry_state: click.echo(
+                _(
+                    "  HTTP 500 from registry, retrying in {wait:.0f}s (attempt {attempt}/5)...",
+                    wait=retry_state.next_action.sleep if retry_state.next_action else 0,
+                    attempt=retry_state.attempt_number + 1,
+                ),
+                err=True,
+            ),
+            reraise=True,
         )
-        if result.returncode != 0:
+        def _attempt(_cmd: list[str] = cmd) -> subprocess.CompletedProcess[str]:
+            return _run_push(_cmd)
+
+        try:
+            result = _attempt()
+        except PushHTTP500Error as e:
             click.echo(
-                _("Push failed for {tag}: {error}", tag=ft, error=result.stderr.strip()),
+                _("Push failed for {tag}: {error}", tag=ft, error=str(e)),
                 err=True,
             )
             all_ok = False
-        else:
+            continue
+
+        if result.returncode == 0:
             click.echo(f"Pushed {ft}")
+            continue
+        combined_output = (result.stdout or "").strip()
+        # Gitea #31964: push fails because tag already exists.
+        # Delete the old manifest and retry once.
+        if username and token and "already exists" in combined_output.lower():
+            click.echo("  Tag exists (Gitea #31964), deleting old manifest and retrying...")
+            delete_remote_manifest(
+                registry,
+                spec.name,
+                tag,
+                username,
+                token,
+                dry_run=dry_run,
+            )
+            click.echo(f"  Retrying push {ft}...")
+            result = subprocess.run(  # nosec B603
+                cmd,
+                stdout=subprocess.PIPE,
+                stderr=subprocess.STDOUT,
+                text=True,
+                check=False,
+            )
+            if result.returncode == 0:
+                click.echo(f"Pushed {ft} (after retry)")
+                continue
+            combined_output = (result.stdout or "").strip()
+        click.echo(
+            _("Push failed for {tag}: {error}", tag=ft, error=combined_output),
+            err=True,
+        )
+        all_ok = False
     return all_ok
 
 
@@ -317,11 +474,15 @@ def main(
             raise click.ClickException(_("Registry login failed"))
 
     failed: list[str] = []
+    push_username = ""  # nosec B105
+    push_token = ""  # nosec B105
+    if push:
+        push_username, push_token = _get_registry_creds()
     for spec in specs:
         if not build_image(spec, registry, dry_run=dry_run, pull=pull):
             failed.append(spec.name)
             continue
-        if push and not push_image(spec, registry, dry_run=dry_run):  # type: ignore[arg-type]
+        if push and not push_image(spec, registry, dry_run=dry_run, username=push_username, token=push_token):  # type: ignore[arg-type]
             failed.append(spec.name)
 
     if failed:

src/devx/tools/check_alert_rules.py

@@ -0,0 +1,86 @@
+"""Validate Prometheus alert rules with promtool check rules.
+
+Renders an alert-rules Jinja2 template with test values and validates
+the output with ``promtool check rules``. Exits 0 if valid, non-zero
+otherwise. Skips (exits 0) if promtool is not on PATH.
+
+Usage::
+
+    python -m devx.tools.check_alert_rules \\
+        --template-path ansible/roles/observability/templates \\
+        --template-name alert-rules.yml.j2
+
+    # With extra template variables:
+    python -m devx.tools.check_alert_rules \\
+        --template-path ansible/roles/observability/templates \\
+        --template-name alert-rules.yml.j2 \\
+        --var grafana_base_url=https://grafana.test.example.com
+"""
+
+from __future__ import annotations
+
+import shutil
+import subprocess  # nosec B404 — used to run promtool, a trusted binary
+import sys
+import tempfile
+from pathlib import Path
+
+import click
+
+from devx.utils.jinja import make_env, render_template
+
+
+@click.command()
+@click.option(
+    "--template-path",
+    type=click.Path(exists=True, path_type=Path),
+    required=True,
+    help="Path to the directory containing the Jinja2 template.",
+)
+@click.option(
+    "--template-name",
+    default="alert-rules.yml.j2",
+    help="Name of the Jinja2 template file to render.",
+)
+@click.option(
+    "--var",
+    "template_vars",
+    multiple=True,
+    help="Template variables in key=value format (can be repeated). "
+    "Example: --var grafana_base_url=https://grafana.example.com",
+)
+def main(template_path: Path, template_name: str, template_vars: tuple[str, ...]) -> None:
+    """Validate rendered alert rules with promtool."""
+    if not shutil.which("promtool"):
+        click.echo("promtool not found in PATH — skipping alert rules validation")
+        return
+
+    # Parse template variables
+    kwargs: dict[str, str] = {}
+    for v in template_vars:
+        if "=" in v:
+            key, value = v.split("=", 1)
+            kwargs[key] = value
+
+    env = make_env(str(template_path))
+    output = render_template(env, template_name, **kwargs)
+
+    with tempfile.NamedTemporaryFile(mode="w", suffix=".yml", delete=False) as f:
+        f.write(output)
+        tmp_path = f.name
+
+    click.echo("[check-alert-rules] Validating rendered rules with promtool...")
+    result = subprocess.run(  # nosec
+        ["promtool", "check", "rules", tmp_path],
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+    click.echo(result.stdout, nl=False)
+    if result.returncode != 0:
+        click.echo(result.stderr, nl=False, err=True)
+    sys.exit(result.returncode)
+
+
+if __name__ == "__main__":  # pragma: no cover
+    main()

src/devx/tools/check_ansible_no_log.py

@@ -0,0 +1,232 @@
+"""Check Ansible tasks for missing no_log on secret-handling tasks.
+
+ansible-lint's built-in ``no-log-password`` rule only fires when a module
+parameter is literally named ``*password*`` and there's a loop. It does
+NOT catch:
+
+- Shell/command tasks that interpolate ``{{ _secrets.* }}`` or
+  ``{{ *password* }}`` variables
+- Template/copy tasks that render secret values without ``no_log``
+
+This script fills that gap by scanning all Ansible task files for
+variables that look like secrets (``_secrets.*``, ``*password*``,
+``*secret*``, ``*token*``, ``*api_key*``) and verifying that the task
+has ``no_log`` set to a non-False value.
+
+Usage::
+
+    python -m devx.tools.check_ansible_no_log
+    python -m devx.tools.check_ansible_no_log --path ansible/roles/my_role
+    python -m devx.tools.check_ansible_no_log --ansible-dir ansible/roles
+
+Exit code 0 if all secret-handling tasks have no_log, 1 otherwise.
+"""
+
+from __future__ import annotations
+
+import re
+import sys
+from pathlib import Path
+
+import click
+import yaml
+
+REPO_ROOT = Path.cwd()
+DEFAULT_ANSIBLE_DIR = REPO_ROOT / "ansible"
+
+# Patterns that indicate a task is handling secrets.
+# We only match Jinja-interpolated variables ({{ ... }}) to avoid false
+# positives from field names like "password" in module params or task names.
+SECRET_PATTERNS = [
+    # {{ _secrets.anything }} or {{ _secrets['anything'] }}
+    re.compile(r"\{\{[^}]*_secrets\.", re.IGNORECASE),
+    # {{ anything_password }} but NOT the word "password" in a string literal
+    re.compile(r"\{\{[^}]*password", re.IGNORECASE),
+    # {{ anything_secret }}
+    re.compile(r"\{\{[^}]*_secret\b", re.IGNORECASE),
+    # {{ anything_api_key }}
+    re.compile(r"\{\{[^}]*api_key", re.IGNORECASE),
+    # {{ anything_token }} (but not loop tokens like {{ loop_token }})
+    re.compile(r"\{\{[^}]*(?:vault_token|auth_token|access_token|bot_token)", re.IGNORECASE),
+]
+
+# Task keys whose values might contain secret references
+TASK_VALUE_KEYS = {
+    "shell",
+    "command",
+    "ansible.builtin.shell",
+    "ansible.builtin.command",
+    "ansible.builtin.template",
+    "ansible.builtin.copy",
+    "ansible.builtin.debug",
+    "template",
+    "copy",
+    "debug",
+    "cmd",
+    "msg",
+    "content",
+}
+
+# Keys that are NOT secret-bearing (task metadata, not values)
+NON_VALUE_KEYS = {
+    "name",
+    "when",
+    "loop",
+    "loop_control",
+    "changed_when",
+    "failed_when",
+    "no_log",
+    "register",
+    "tags",
+    "vars",
+    "become",
+    "become_user",
+    "delegate_to",
+    "run_once",
+    "environment",
+    "with_items",
+    "with_dict",
+    "with_list",
+}
+
+
+def _contains_secret(value: object) -> bool:
+    """Recursively check if a value contains secret-like variable references."""
+    if isinstance(value, str):
+        return any(p.search(value) for p in SECRET_PATTERNS)
+    if isinstance(value, dict):
+        return any(_contains_secret(v) for v in value.values())
+    if isinstance(value, list):
+        return any(_contains_secret(item) for item in value)
+    return False
+
+
+def _has_no_log(task: dict) -> bool:
+    """Check if a task has no_log set to a non-False value."""
+    no_log = task.get("no_log", False)
+    # Jinja expressions (e.g. "{{ not debug_mode }}") count as set
+    return no_log is not False and no_log is not None
+
+
+def _check_task(task: dict, file_path: Path, task_num: int) -> list[str]:
+    """Check a single task for missing no_log on secret values.
+
+    Returns a list of violation messages (empty if OK).
+    """
+    violations: list[str] = []
+
+    # Skip tasks that already have no_log
+    if _has_no_log(task):
+        return violations
+
+    # Check all string values in the task for secret references
+    has_secrets = False
+    for key, value in task.items():
+        if key in NON_VALUE_KEYS:
+            continue
+        # Check action module params (shell, command, copy, template, etc.)
+        if _contains_secret(value):
+            has_secrets = True
+            break
+
+    if has_secrets:
+        task_name = task.get("name", "<unnamed>")
+        violations.append(
+            f"{file_path}:{task_num}: Task '{task_name}' references secrets "
+            f"but has no no_log. Add `no_log: true` or "
+            f'`no_log: "{{{{ not (debug_mode | default(false) | bool) }}}}"` '
+            f"to prevent credential leakage in Ansible output."
+        )
+
+    return violations
+
+
+def check_directory(ansible_dir: Path) -> list[str]:
+    """Check all Ansible task files in a directory tree."""
+    all_violations: list[str] = []
+
+    # Find all task files
+    task_files = list(ansible_dir.rglob("tasks/*.yml"))
+    task_files += list(ansible_dir.rglob("tasks/*.yaml"))
+    # Also check playbook files
+    task_files += list(ansible_dir.glob("playbooks/*.yml"))
+
+    for task_file in sorted(task_files):
+        # Skip molecule test files
+        if "molecule" in task_file.parts:
+            continue
+
+        try:
+            with task_file.open() as f:
+                docs = list(yaml.safe_load_all(f))
+        except (yaml.YAMLError, OSError):
+            continue
+
+        for doc in docs:
+            if not doc:
+                continue
+
+            # Task files are bare lists of tasks; playbook files are
+            # lists of plays (each play is a dict with 'hosts' key)
+            if isinstance(doc, list):
+                is_plays = isinstance(doc[0], dict) and "hosts" in doc[0]
+                if not is_plays:
+                    for i, task in enumerate(doc):
+                        if not isinstance(task, dict):
+                            continue
+                        all_violations.extend(_check_task(task, task_file, i + 1))
+                    continue
+                plays = doc
+            elif isinstance(doc, dict):
+                plays = [doc]
+            else:
+                continue
+
+            for play in plays:
+                if not isinstance(play, dict):
+                    continue
+                for task_section in ("tasks", "pre_tasks", "post_tasks", "handlers"):
+                    tasks = play.get(task_section, [])
+                    if not isinstance(tasks, list):
+                        continue
+                    for i, task in enumerate(tasks):
+                        if not isinstance(task, dict):
+                            continue
+                        all_violations.extend(_check_task(task, task_file, i + 1))
+
+    return all_violations
+
+
+@click.command()
+@click.option(
+    "--path",
+    type=click.Path(exists=True, path_type=Path),
+    help="Check a specific file or directory (default: ansible/).",
+)
+@click.option(
+    "--ansible-dir",
+    type=click.Path(exists=True, path_type=Path),
+    default=None,
+    help="Override the default ansible directory (default: ansible/).",
+)
+def main(path: Path | None, ansible_dir: Path | None) -> None:
+    """Check that Ansible tasks handling secrets have no_log set."""
+    target = path or ansible_dir or DEFAULT_ANSIBLE_DIR
+    if not target.is_dir():
+        click.echo(f"Error: {target} is not a directory", err=True)
+        sys.exit(2)
+
+    violations = check_directory(target)
+
+    if violations:
+        click.echo(f"Found {len(violations)} task(s) handling secrets without no_log:\n")
+        for v in violations:
+            click.echo(f"  {v}")
+        click.echo(f"\nTotal: {len(violations)} violation(s).")
+        sys.exit(1)
+
+    click.echo(f"[check-ansible-no-log] All secret-handling tasks have no_log. ({target})")
+
+
+if __name__ == "__main__":  # pragma: no cover
+    main()

src/devx/tools/check_ansible_no_state_absent_on_db.py

@@ -0,0 +1,176 @@
+"""Check Ansible tasks for ``state: absent`` on database data directories.
+
+This is a static analysis lint check that runs in CI (``make lint-ci``)
+to prevent the class of bug that caused the 2026-07-22 production outage
+(ADR-0028): a ``state: absent`` on a PostgreSQL data directory path that
+fired on every deploy and wiped the ZITADEL database.
+
+The existing unit test ``scripts/tests/test_no_zitadel_db_wipe.py`` covers
+the same concern as a regression test. This lint check runs earlier in
+the pipeline (before tests) and covers ALL roles and playbooks, not just
+the ZITADEL role.
+
+Allowed contexts (where DB recreation is legitimate):
+- PostgreSQL major version upgrades (``upgrade-postgres``, ``PG_VERSION``)
+- Explicit ``# lint:allow-state-absent`` comment on the task
+
+Usage::
+
+    python -m devx.tools.check_ansible_no_state_absent_on_db
+    python -m devx.tools.check_ansible_no_state_absent_on_db --path ansible/roles/zitadel/tasks/main.yml
+
+Exit code 0 if no violations found, 1 otherwise.
+"""
+
+from __future__ import annotations
+
+import re
+import sys
+from pathlib import Path
+
+import click
+
+REPO_ROOT = Path.cwd()
+DEFAULT_ANSIBLE_DIRS: list[Path] = [
+    REPO_ROOT / "ansible" / "playbooks",
+    REPO_ROOT / "ansible" / "roles",
+]
+
+# Database data directory path patterns.
+# These match the DIRECTORY path, not individual files within it.
+# Removing a stale config file (e.g. postgresql.conf) is safe; removing
+# the entire data directory is not.
+DB_PATH_PATTERNS = (
+    re.compile(r"postgres/zitadel-db", re.IGNORECASE),
+    re.compile(r"postgres/\w+-db", re.IGNORECASE),
+    re.compile(r"/var/lib/postgresql/data", re.IGNORECASE),
+    re.compile(r"/var/lib/postgresql/data/\w+-db", re.IGNORECASE),
+)
+
+# Destructive operations
+DESTRUCTIVE_PATTERNS = (
+    re.compile(r"state:\s*absent", re.IGNORECASE),
+    re.compile(r"rm\s+-rf.*\bdb\b", re.IGNORECASE),
+)
+
+# Allowed contexts where DB recreation is legitimate
+ALLOWED_CONTEXT_KEYWORDS = (
+    "upgrade-postgres",
+    "PG_VERSION",
+    "pg_version",
+)
+
+# Comment marker to explicitly allow state: absent on a specific task
+ALLOW_MARKER = "lint:allow-state-absent"
+
+
+def _find_task_files(base: Path) -> list[Path]:
+    """Find all YAML task files under a base directory, skipping molecule."""
+    if base.is_file() and base.suffix in (".yml", ".yaml"):
+        return [base]
+    if not base.is_dir():
+        return []
+    files: list[Path] = []
+    for f in sorted(base.rglob("*.yml")) + sorted(base.rglob("*.yaml")):
+        if "molecule" in f.parts:
+            continue
+        files.append(f)
+    return files
+
+
+def _check_file(filepath: Path, repo_root: Path) -> list[str]:
+    """Check a YAML file for state: absent on DB data directory paths.
+
+    Returns a list of violation messages (empty if clean).
+    """
+    try:
+        content = filepath.read_text(encoding="utf-8")
+    except (OSError, UnicodeDecodeError):
+        return []
+
+    # Quick check: if no DB path pattern appears anywhere, skip
+    if not any(p.search(content) for p in DB_PATH_PATTERNS):
+        return []
+
+    try:
+        display_path = filepath.relative_to(repo_root)
+    except ValueError:
+        display_path = filepath
+
+    violations: list[str] = []
+    lines = content.splitlines()
+
+    for i, line in enumerate(lines):
+        for db_pattern in DB_PATH_PATTERNS:
+            if not db_pattern.search(line):
+                continue
+
+            # Check surrounding context (±5 lines) for destructive operations
+            context_start = max(0, i - 5)
+            context_end = min(len(lines), i + 6)
+            context = "\n".join(lines[context_start:context_end])
+
+            # Skip if in an allowed context (PG upgrade)
+            if any(kw in context for kw in ALLOWED_CONTEXT_KEYWORDS):
+                continue
+
+            # Skip if the allow marker comment is in the context
+            if ALLOW_MARKER in context:
+                continue
+
+            for dp in DESTRUCTIVE_PATTERNS:
+                if dp.search(context):
+                    violations.append(
+                        f"{display_path}:{i + 1} — destructive operation "
+                        f"({dp.pattern!r}) near DB data directory path "
+                        f"({db_pattern.pattern!r}). "
+                        f"Database directories must never be wiped automatically (ADR-0028). "
+                        f"If this is legitimate (e.g. PG upgrade), add "
+                        f"#{ALLOW_MARKER} to the task."
+                    )
+                    break
+
+    return violations
+
+
+@click.command()
+@click.option(
+    "--path",
+    type=click.Path(exists=True, path_type=Path),
+    help="Check a specific file or directory (default: ansible/playbooks + ansible/roles).",
+)
+@click.option(
+    "--ansible-dir",
+    "ansible_dirs",
+    type=click.Path(exists=True, path_type=Path),
+    multiple=True,
+    default=None,
+    help="Override the default ansible directories (can be repeated). Defaults to ansible/playbooks and ansible/roles.",
+)
+def main(path: Path | None, ansible_dirs: tuple[Path, ...]) -> None:
+    """Check that no Ansible task uses state: absent on a DB data directory."""
+    dirs = list(ansible_dirs) if ansible_dirs else DEFAULT_ANSIBLE_DIRS
+    if path:
+        files = _find_task_files(path)
+    else:
+        files: list[Path] = []
+        for d in dirs:
+            files.extend(_find_task_files(d))
+
+    all_violations: list[str] = []
+    for f in files:
+        all_violations.extend(_check_file(f, REPO_ROOT))
+
+    if all_violations:
+        click.echo("[check-ansible-no-state-absent-on-db] FAIL: destructive operations on DB paths:")
+        for v in all_violations:
+            click.echo(f"  - {v}")
+        click.echo(f"\nTotal: {len(all_violations)} violation(s).")
+        click.echo("Database data directories must never be wiped automatically (ADR-0028).")
+        sys.exit(1)
+    else:
+        click.echo("[check-ansible-no-state-absent-on-db] OK: no destructive operations on DB paths.")
+
+
+if __name__ == "__main__":  # pragma: no cover
+    main()

src/devx/tools/check_ansible_patterns.py

@@ -0,0 +1,345 @@
+"""Check Ansible tasks for dangerous patterns that mask failures.
+
+This check addresses the gap identified in the testing-strategy audit:
+the automated PR review only checks Python files, and ``ansible-lint``
+runs at ``profile: basic`` which does not catch dangerous patterns like:
+
+- ``|| true`` on tasks that are NOT cleanup/idempotency operations
+- ``failed_when: false`` on critical tasks (e.g. DB operations)
+- ``2>/dev/null`` on tasks where stderr contains important diagnostics
+
+Most ``|| true`` and ``2>/dev/null`` instances in the codebase are
+legitimate (container removal, journalctl, apt-get, docker prune, SUID
+removal). This check flags only instances that are NOT in a known-safe
+context. Tasks can also opt out with a ``# lint:allow-failure-masking``
+comment.
+
+Usage::
+
+    python -m devx.tools.check_ansible_patterns
+    python -m devx.tools.check_ansible_patterns --path ansible/roles/app_container/tasks/main.yml
+
+Exit code 0 if no violations found, 1 otherwise.
+"""
+
+from __future__ import annotations
+
+import re
+import sys
+from pathlib import Path
+
+import click
+import yaml
+
+REPO_ROOT = Path.cwd()
+DEFAULT_ANSIBLE_DIRS: list[Path] = [
+    REPO_ROOT / "ansible" / "playbooks",
+    REPO_ROOT / "ansible" / "roles",
+]
+
+# Comment marker to explicitly allow a pattern on a specific task
+ALLOW_MARKER = "lint:allow-failure-masking"
+
+# Patterns that mask failures when used in shell/command tasks
+OR_TRUE_PATTERN = re.compile(r"\|\|\s*true\b", re.IGNORECASE)
+REDIRECT_DEVNULL_PATTERN = re.compile(r"2>/dev/null")
+
+# Module keys that accept shell/command strings
+SHELL_MODULE_KEYS = frozenset(
+    {
+        "shell",
+        "command",
+        "ansible.builtin.shell",
+        "ansible.builtin.command",
+        "cmd",
+        "ansible.builtin.raw",
+        "raw",
+    }
+)
+
+# Task keys whose values might contain shell commands
+COMMAND_VALUE_KEYS = frozenset(
+    {
+        "shell",
+        "command",
+        "ansible.builtin.shell",
+        "ansible.builtin.command",
+        "cmd",
+        "raw",
+        "ansible.builtin.raw",
+    }
+)
+
+# Legitimate contexts where || true or 2>/dev/null are safe.
+# These are command prefixes or task names that indicate cleanup/idempotency.
+LEGITIMATE_COMMAND_PREFIXES = (
+    # Container/process removal (may not exist)
+    "docker rm",
+    "docker stop",
+    "docker rmi",
+    "docker network rm",
+    "docker volume rm",
+    "pkill",
+    "kill",
+    # Cleanup commands that are expected to sometimes fail
+    "journalctl --vacuum",
+    "apt-get clean",
+    "apt-get autoremove",
+    "docker image prune",
+    "docker container prune",
+    "docker volume prune",
+    "docker builder prune",
+    "find / -name",
+    # SUID removal (binaries may not exist)
+    "chmod",
+    "rm -f",
+    # Network connection checks (may fail if not connected)
+    "docker network connect",
+    # Prometheus snapshot API (may fail if no snapshot)
+    "curl.*api/v2/admin/tsdb/snapshot",
+)
+
+LEGITIMATE_TASK_NAME_KEYWORDS = (
+    "remove",
+    "cleanup",
+    "clean up",
+    "prune",
+    "purge",
+    "disconnect",
+    "stop",
+    "kill",
+    "strip suid",
+    "suid",
+    "vacuum",
+    "ensure.*absent",
+    "may not exist",
+    "if exists",
+    "optional",
+    "best effort",
+    "no-op",
+    "noop",
+    "idempotent",
+    "sync",
+)
+
+# Tasks with failed_when: false that are critical and should not mask failures.
+# Only flag operations that SHOULD fail loudly — writing secrets, provisioning
+# users, creating OIDC apps. Do NOT flag stop/start/check/wait/migrate/restore
+# operations where failed_when: false is legitimate (container may not exist,
+# may already be stopped, etc.).
+CRITICAL_TASK_KEYWORDS = (
+    "password",
+    "secret",
+    "provision",
+    "oidc",
+)
+
+# Task name keywords that indicate failed_when: false is legitimate
+LEGITIMATE_FAILED_WHEN_KEYWORDS = (
+    "stop",
+    "start",
+    "check",
+    "wait",
+    "migrate",
+    "restart",
+    "rebuild",
+    "restore",
+    "remove",
+    "cleanup",
+    "sync",
+    "download",
+    "extract",
+    "verify",
+)
+
+
+def _is_legitimate_or_true(command_str: str, task_name: str) -> bool:
+    """Check if a || true in a command is in a legitimate context."""
+    # Check task name for legitimate keywords
+    name_lower = task_name.lower()
+    if any(re.search(kw, name_lower) for kw in LEGITIMATE_TASK_NAME_KEYWORDS):
+        return True
+
+    # Check command prefix for legitimate patterns
+    cmd_lower = command_str.lower()
+    return any(re.search(prefix, cmd_lower) for prefix in LEGITIMATE_COMMAND_PREFIXES)
+
+
+def _is_legitimate_devnull(command_str: str, task_name: str) -> bool:
+    """Check if a 2>/dev/null in a command is in a legitimate context."""
+    # 2>/dev/null is almost always safe — it suppresses stderr noise.
+    # Only flag it if the task is critical (DB, backup, OIDC) AND
+    # there's no || true (which is the more dangerous pattern).
+    return _is_legitimate_or_true(command_str, task_name)
+
+
+def _check_task(task: dict, filepath: Path, task_num: int, repo_root: Path) -> list[str]:
+    """Check a single task for dangerous failure-masking patterns."""
+    violations: list[str] = []
+
+    try:
+        display_path = filepath.relative_to(repo_root)
+    except ValueError:
+        display_path = filepath
+
+    task_name = task.get("name", "<unnamed>")
+
+    # Check for the allow marker in the task name
+    # (YAML comments are not preserved by safe_load, so we check the
+    # task name for the marker as a workaround)
+    if ALLOW_MARKER in task_name:
+        return violations
+
+    # Check for || true in command/shell values
+    for key in COMMAND_VALUE_KEYS:
+        value = task.get(key)
+        if value is None:
+            continue
+        value_str = str(value)
+        if OR_TRUE_PATTERN.search(value_str) and not _is_legitimate_or_true(value_str, task_name):
+            violations.append(
+                f"{display_path}:{task_num} — task '{task_name}' uses "
+                f"'|| true' in {key} which may mask real failures. "
+                f"If this is a cleanup/idempotency operation, rename the "
+                f"task to include 'remove'/'cleanup'/'prune' or add "
+                f"#{ALLOW_MARKER} to the task."
+            )
+
+    # Check for failed_when: false on critical tasks
+    failed_when = task.get("failed_when")
+    if failed_when is False:
+        name_lower = task_name.lower()
+        # Skip if the task name indicates a legitimate failed_when: false context
+        is_legitimate = any(kw in name_lower for kw in LEGITIMATE_FAILED_WHEN_KEYWORDS)
+        if not is_legitimate:
+            for kw in CRITICAL_TASK_KEYWORDS:
+                if kw in name_lower:
+                    violations.append(
+                        f"{display_path}:{task_num} — critical task '{task_name}' "
+                        f"has failed_when: false, which masks failures on "
+                        f"a {kw}-related operation. Remove failed_when: false "
+                        f"or add #{ALLOW_MARKER} if masking is intentional."
+                    )
+                    break
+
+    return violations
+
+
+def _check_file(filepath: Path, repo_root: Path) -> list[str]:
+    """Check a YAML file for dangerous failure-masking patterns."""
+    try:
+        content = filepath.read_text(encoding="utf-8")
+    except (OSError, UnicodeDecodeError):
+        return []
+
+    # Quick check: if no patterns appear, skip
+    if not (
+        OR_TRUE_PATTERN.search(content) or "failed_when: false" in content or REDIRECT_DEVNULL_PATTERN.search(content)
+    ):
+        return []
+
+    # Check for allow markers in comments
+    has_allow_marker = ALLOW_MARKER in content
+
+    try:
+        docs = list(yaml.safe_load_all(content))
+    except yaml.YAMLError:
+        return []
+
+    violations: list[str] = []
+
+    for doc in docs:
+        if not doc:
+            continue
+        if isinstance(doc, list):
+            for i, item in enumerate(doc):
+                if isinstance(item, dict):
+                    if any(k in item for k in ("tasks", "pre_tasks", "post_tasks", "handlers")):
+                        _check_tasks(item, filepath, violations, repo_root)
+                    else:
+                        violations.extend(_check_task(item, filepath, i + 1, repo_root))
+                        block = item.get("block")
+                        if isinstance(block, list):
+                            for j, bt in enumerate(block):
+                                if isinstance(bt, dict):
+                                    violations.extend(_check_task(bt, filepath, i + j + 1, repo_root))
+        elif isinstance(doc, dict):
+            _check_tasks(doc, filepath, violations, repo_root)
+
+    # Filter out violations if the allow marker is present in the file
+    # (coarse-grained opt-out for files with many legitimate uses)
+    if has_allow_marker:
+        violations = []
+
+    return violations
+
+
+def _check_tasks(doc: dict, filepath: Path, errors: list[str], repo_root: Path) -> None:
+    """Check top-level tasks and nested task sections in a playbook doc."""
+    for section_key in ("tasks", "pre_tasks", "post_tasks", "handlers"):
+        section = doc.get(section_key)
+        if isinstance(section, list):
+            for i, task in enumerate(section):
+                if isinstance(task, dict):
+                    errors.extend(_check_task(task, filepath, i + 1, repo_root))
+                    block = task.get("block")
+                    if isinstance(block, list):
+                        for j, bt in enumerate(block):
+                            if isinstance(bt, dict):
+                                errors.extend(_check_task(bt, filepath, i + j + 1, repo_root))
+
+
+def _find_task_files(base: Path) -> list[Path]:
+    """Find all YAML task files under a base directory, skipping molecule."""
+    if base.is_file() and base.suffix in (".yml", ".yaml"):
+        return [base]
+    if not base.is_dir():
+        return []
+    files: list[Path] = []
+    for f in sorted(base.rglob("*.yml")) + sorted(base.rglob("*.yaml")):
+        if "molecule" in f.parts:
+            continue
+        files.append(f)
+    return files
+
+
+@click.command()
+@click.option(
+    "--path",
+    type=click.Path(exists=True, path_type=Path),
+    help="Check a specific file or directory (default: ansible/playbooks + ansible/roles).",
+)
+@click.option(
+    "--ansible-dir",
+    "ansible_dirs",
+    type=click.Path(exists=True, path_type=Path),
+    multiple=True,
+    default=None,
+    help="Override the default ansible directories (can be repeated). Defaults to ansible/playbooks and ansible/roles.",
+)
+def main(path: Path | None, ansible_dirs: tuple[Path, ...]) -> None:
+    """Check Ansible tasks for dangerous failure-masking patterns."""
+    dirs = list(ansible_dirs) if ansible_dirs else DEFAULT_ANSIBLE_DIRS
+    if path:
+        files = _find_task_files(path)
+    else:
+        files: list[Path] = []
+        for d in dirs:
+            files.extend(_find_task_files(d))
+
+    all_violations: list[str] = []
+    for f in files:
+        all_violations.extend(_check_file(f, REPO_ROOT))
+
+    if all_violations:
+        click.echo("[check-ansible-patterns] FAIL: dangerous failure-masking patterns found:")
+        for v in all_violations:
+            click.echo(f"  - {v}")
+        click.echo(f"\nTotal: {len(all_violations)} violation(s).")
+        sys.exit(1)
+    else:
+        click.echo("[check-ansible-patterns] OK: no dangerous failure-masking patterns.")
+
+
+if __name__ == "__main__":  # pragma: no cover
+    main()

src/devx/tools/check_ansible_set_fact_to_json.py

@@ -0,0 +1,196 @@
+"""Check that Ansible ``set_fact`` tasks don't misuse ``| to_json``.
+
+This prevents the class of bug where ``set_fact`` tasks use
+``{{ targets | to_json }}`` to store Python lists, but ``to_json``
+converts native types to JSON strings. Ansible then stored the result
+as a string, so iterating over the fact yielded individual characters
+instead of list items, causing ``object of type 'str' has no attribute
+'ip'`` errors.
+
+The check scans all Ansible task files (playbooks and role tasks) for
+``set_fact`` tasks where any value uses ``| to_json`` or ``| to_nice_json``
+and flags them as potential bugs.
+
+``| to_json`` is legitimate in Jinja2 templates (e.g., rendering JSON
+config files) but almost never correct in ``set_fact`` — the fact should
+store the native Python type so downstream tasks can iterate/index it.
+
+Usage::
+
+    python -m devx.tools.check_ansible_set_fact_to_json
+    python -m devx.tools.check_ansible_set_fact_to_json --path ansible/playbooks/deploy.yml
+
+Exit code 0 if no misuses found, 1 otherwise.
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+import click
+import yaml
+
+REPO_ROOT = Path.cwd()
+DEFAULT_ANSIBLE_DIRS: list[Path] = [
+    REPO_ROOT / "ansible" / "playbooks",
+    REPO_ROOT / "ansible" / "roles",
+]
+
+TO_JSON_FILTERS = ("| to_json", "| to_nice_json", "|to_json", "|to_nice_json")
+
+
+def _find_task_files(base: Path) -> list[Path]:
+    """Find all YAML task files under a base directory."""
+    if base.is_file() and base.suffix in (".yml", ".yaml"):
+        return [base]
+    if not base.is_dir():
+        return []
+    return sorted(base.rglob("*.yml")) + sorted(base.rglob("*.yaml"))
+
+
+def _check_file(filepath: Path, repo_root: Path) -> list[str]:
+    """Check a single YAML file for set_fact + to_json misuse.
+
+    Returns a list of error messages (empty if all OK).
+    """
+    errors: list[str] = []
+    content = filepath.read_text(encoding="utf-8")
+
+    # Multi-document YAML (--- separators) is common in playbooks
+    try:
+        docs = list(yaml.safe_load_all(content))
+    except yaml.YAMLError as exc:
+        return [f"{filepath}: cannot parse YAML: {exc}"]
+
+    for doc in docs:
+        if isinstance(doc, list):
+            # Could be a playbook (list of plays) or a role tasks file (list of tasks)
+            for item in doc:
+                if isinstance(item, dict):
+                    if any(k in item for k in ("tasks", "pre_tasks", "post_tasks", "handlers", "roles")):
+                        # It's a play
+                        _check_tasks(item, filepath, errors, repo_root)
+                    else:
+                        # It's a bare task (role tasks file)
+                        _check_task(item, filepath, errors, repo_root)
+                        block = item.get("block")
+                        if isinstance(block, list):
+                            _check_task_list(block, filepath, errors, repo_root)
+        elif isinstance(doc, dict):
+            # Role tasks file or single play — _check_tasks handles all task sections
+            _check_tasks(doc, filepath, errors, repo_root)
+
+    return errors
+
+
+def _check_tasks(doc: dict, filepath: Path, errors: list[str], repo_root: Path) -> None:
+    """Check top-level tasks and nested task sections in a playbook doc."""
+    tasks = doc.get("tasks")
+    if isinstance(tasks, list):
+        _check_task_list(tasks, filepath, errors, repo_root)
+    for role_key in ("pre_tasks", "post_tasks", "handlers"):
+        section = doc.get(role_key)
+        if isinstance(section, list):
+            _check_task_list(section, filepath, errors, repo_root)
+    # Check tasks in roles imported via `roles:` key
+    roles = doc.get("roles")
+    if isinstance(roles, list):
+        for role_entry in roles:
+            if isinstance(role_entry, dict):
+                role_tasks = role_entry.get("tasks")
+                if isinstance(role_tasks, list):
+                    _check_task_list(role_tasks, filepath, errors, repo_root)
+
+
+def _check_task_list(tasks: list, filepath: Path, errors: list[str], repo_root: Path) -> None:
+    """Check a list of task definitions for set_fact + to_json."""
+    for task in tasks:
+        if not isinstance(task, dict):
+            continue
+        _check_task(task, filepath, errors, repo_root)
+        # Check nested block tasks
+        block = task.get("block")
+        if isinstance(block, list):
+            _check_task_list(block, filepath, errors, repo_root)
+
+
+def _check_task(task: dict, filepath: Path, errors: list[str], repo_root: Path) -> None:
+    """Check a single task for set_fact + to_json misuse."""
+    # Detect set_fact — could be a module name key or ansible.builtin.set_fact
+    has_set_fact = False
+    for key in task:
+        if key in {"set_fact", "ansible.builtin.set_fact"}:
+            has_set_fact = True
+            break
+
+    if not has_set_fact:
+        return
+
+    set_fact_body = task.get("set_fact") or task.get("ansible.builtin.set_fact")
+    if not isinstance(set_fact_body, dict):
+        return
+
+    task_name = task.get("name", "(unnamed)")
+
+    for fact_name, fact_value in set_fact_body.items():
+        if fact_name in ("cacheable",):
+            continue
+        value_str = str(fact_value)
+        for filter_pattern in TO_JSON_FILTERS:
+            if filter_pattern in value_str:
+                try:
+                    display_path = filepath.relative_to(repo_root)
+                except ValueError:
+                    display_path = filepath
+                errors.append(
+                    f"{display_path}: task '{task_name}' "
+                    f"sets fact '{fact_name}' with '{filter_pattern.strip()}' "
+                    f"— this converts native Python types to JSON strings. "
+                    f"Remove the filter to preserve the native type, or use "
+                    f"'| from_json' in the consuming task if the string "
+                    f"representation is intentional."
+                )
+                break  # One error per fact is enough
+
+
+@click.command()
+@click.option(
+    "--path",
+    type=click.Path(exists=True, path_type=Path),
+    help="Check a specific file or directory (default: ansible/playbooks + ansible/roles).",
+)
+@click.option(
+    "--ansible-dir",
+    "ansible_dirs",
+    type=click.Path(exists=True, path_type=Path),
+    multiple=True,
+    default=None,
+    help="Override the default ansible directories (can be repeated). Defaults to ansible/playbooks and ansible/roles.",
+)
+def main(path: Path | None, ansible_dirs: tuple[Path, ...]) -> None:
+    """Check that set_fact tasks don't misuse to_json."""
+    dirs = list(ansible_dirs) if ansible_dirs else DEFAULT_ANSIBLE_DIRS
+    if path:
+        files = _find_task_files(path)
+    else:
+        files: list[Path] = []
+        for d in dirs:
+            files.extend(_find_task_files(d))
+
+    all_errors: list[str] = []
+    for f in files:
+        errors = _check_file(f, REPO_ROOT)
+        all_errors.extend(errors)
+
+    if all_errors:
+        click.echo("[check-ansible-set-fact-to-json] FAIL: set_fact with to_json found:")
+        for err in all_errors:
+            click.echo(f"  - {err}")
+        sys.exit(1)
+    else:
+        click.echo("[check-ansible-set-fact-to-json] OK: no set_fact tasks misuse to_json.")
+
+
+if __name__ == "__main__":  # pragma: no cover
+    main()

src/devx/tools/check_docker_init.py

@@ -0,0 +1,166 @@
+"""Check that Docker Compose services with healthchecks have ``init: true``.
+
+This prevents zombie process accumulation on production VMs. Without
+``init: true``, Docker uses the container's PID 1 process to reap
+child processes. Many images (especially those using CMD-SHELL
+healthchecks with ``wget``) don't call ``wait()`` on children, causing
+zombies to accumulate.
+
+The check scans all Jinja2 docker-compose templates for services that
+have a ``healthcheck:`` key but no ``init: true`` key. Since the
+templates use Jinja2 syntax (not pure YAML), the check uses text-based
+parsing to identify service blocks and their properties.
+
+Usage::
+
+    python -m devx.tools.check_docker_init
+    python -m devx.tools.check_docker_init --path ansible/roles/observability/templates/docker-compose.yml.j2
+
+Exit code 0 if all services with healthchecks have init: true, 1 otherwise.
+"""
+
+from __future__ import annotations
+
+import re
+import sys
+from pathlib import Path
+
+import click
+
+REPO_ROOT = Path.cwd()
+DEFAULT_TEMPLATES_DIR = REPO_ROOT / "ansible" / "roles"
+
+
+def _find_compose_templates(base: Path) -> list[Path]:
+    """Find all Jinja2 docker-compose templates under a base directory."""
+    if base.is_file():
+        return [base]
+    if not base.is_dir():
+        return []
+    results: list[Path] = []
+    for pattern in ("*docker-compose*", "*compose*"):
+        results.extend(base.rglob(f"{pattern}.yml.j2"))
+        results.extend(base.rglob(f"{pattern}.yaml.j2"))
+    # Also check exporters-compose
+    results.extend(base.rglob("exporters-compose*.j2"))
+    # Deduplicate while preserving order
+    seen: set[Path] = set()
+    unique: list[Path] = []
+    for p in sorted(results):
+        if p not in seen:
+            seen.add(p)
+            unique.append(p)
+    return unique
+
+
+def _parse_services(content: str) -> dict[str, list[str]]:
+    """Parse service blocks from a docker-compose Jinja2 template.
+
+    Returns a mapping of service_name → list of lines in that service block.
+    """
+    lines = content.splitlines()
+    in_services = False
+    services: dict[str, list[str]] = {}
+    current_svc: str | None = None
+    current_lines: list[str] = []
+
+    for line in lines:
+        if line.startswith("services:"):
+            in_services = True
+            continue
+        if not in_services:
+            continue
+        # Top-level keys (networks:, volumes:) end the services section
+        if re.match(r"^(networks|volumes):\s*$", line):
+            if current_svc is not None:
+                services[current_svc] = current_lines
+            current_svc = None
+            in_services = False
+            continue
+        # Service definition: exactly 2-space indent, ends with :
+        # Service names can contain Jinja2 variables like {{ app_name }}
+        # or {{ app_name }}-db. Match: 2-space indent + non-whitespace
+        # chars (including {{ }}, -, _, .) + optional spaces inside {{ }} + :
+        m = re.match(r"^  (\{\{.*?\}\}[a-zA-Z0-9_-]*|[a-zA-Z0-9_().-]+):\s*$", line)
+        if m:
+            if current_svc is not None:
+                services[current_svc] = current_lines
+            current_svc = m.group(1)
+            current_lines = []
+        elif current_svc is not None:
+            current_lines.append(line)
+
+    if current_svc is not None:
+        services[current_svc] = current_lines
+
+    return services
+
+
+def _check_template(filepath: Path, repo_root: Path) -> list[str]:
+    """Check a single docker-compose template for missing init: true.
+
+    Returns a list of error messages (empty if all OK).
+    """
+    errors: list[str] = []
+    content = filepath.read_text(encoding="utf-8")
+
+    if "services:" not in content:
+        return errors
+
+    services = _parse_services(content)
+
+    for svc_name, svc_lines in services.items():
+        svc_text = "\n".join(svc_lines)
+        has_init = "init: true" in svc_text
+        has_healthcheck = "healthcheck:" in svc_text
+        # Skip services that are conditionally included (Jinja2 if blocks)
+        # but still check them — the healthcheck is inside the conditional
+        if has_healthcheck and not has_init:
+            try:
+                display_path = filepath.relative_to(repo_root)
+            except ValueError:
+                display_path = filepath
+            errors.append(
+                f"{display_path}: service '{svc_name}' has a healthcheck "
+                f"but no 'init: true'. Without init: true, CMD-SHELL "
+                f"healthchecks (wget, pgrep) spawn children that become "
+                f"zombies when PID 1 doesn't reap them. Add 'init: true' "
+                f"to enable Docker's built-in tini as PID 1."
+            )
+
+    return errors
+
+
+@click.command()
+@click.option(
+    "--path",
+    type=click.Path(exists=True, path_type=Path),
+    help="Check a specific file or directory (default: ansible/roles/).",
+)
+@click.option(
+    "--templates-dir",
+    type=click.Path(exists=True, path_type=Path),
+    default=None,
+    help="Override the default templates directory (default: ansible/roles/).",
+)
+def main(path: Path | None, templates_dir: Path | None) -> None:
+    """Check that Docker Compose services with healthchecks have init: true."""
+    tdir = templates_dir or DEFAULT_TEMPLATES_DIR
+    files = _find_compose_templates(path) if path else _find_compose_templates(tdir)
+
+    all_errors: list[str] = []
+    for f in files:
+        errors = _check_template(f, tdir)
+        all_errors.extend(errors)
+
+    if all_errors:
+        click.echo("[check-docker-init] FAIL: services with healthchecks missing init: true:")
+        for err in all_errors:
+            click.echo(f"  - {err}")
+        sys.exit(1)
+    else:
+        click.echo("[check-docker-init] OK: all services with healthchecks have init: true.")
+
+
+if __name__ == "__main__":  # pragma: no cover
+    main()

src/devx/tools/check_jinja_expr.py

@@ -0,0 +1,292 @@
+"""Validate Jinja2 expressions in Ansible files by rendering them.
+
+Extracts ``{{ ... }}`` expressions from Ansible YAML files and renders
+each one with Ansible's Jinja2 environment using mock variables. Catches
+errors like reversed filter arguments, undefined filters, and syntax
+errors before pushing to CI.
+
+The check is intentionally lightweight — it doesn't need real Ansible
+facts or variables. It provides common mock values (now(), ansible_*,
+etc.) and renders each expression in isolation. Expressions that fail
+with undefined variables that aren't in the mock set are skipped (not
+all variables can be predicted).
+
+Usage::
+
+    python -m devx.tools.check_jinja_expr
+    python -m devx.tools.check_jinja_expr --path ansible/playbooks/deploy-observability.yml
+
+Exit code 0 if all renderable expressions pass, 1 if any fail.
+"""
+
+from __future__ import annotations
+
+import re
+import sys
+from pathlib import Path
+
+import click
+from jinja2 import Environment
+from jinja2.exceptions import TemplateSyntaxError, UndefinedError
+
+REPO_ROOT = Path.cwd()
+
+
+def _default_ansible_dirs() -> list[Path]:
+    """Return the default directories to scan for Ansible files."""
+    return [
+        REPO_ROOT / "ansible" / "playbooks",
+        REPO_ROOT / "ansible" / "roles",
+    ]
+
+
+# Mock context for rendering Jinja expressions.
+MOCK_CONTEXT: dict[str, object] = {
+    "now": lambda fmt=None: (
+        "2026-01-01T00:00:00+00:00"
+        if fmt
+        else type(
+            "Now",
+            (),
+            {
+                "timestamp": lambda self: 1735689600.0,
+                "strftime": lambda self, fmt: "2026-01-01T00:00:00+00:00",
+            },
+        )()
+    ),
+    "ansible_date_time": {
+        "iso8601": "2026-01-01T00:00:00+00:00",
+        "epoch": "1735689600",
+    },
+    "ansible_facts": {
+        "service_mgr": "systemd",
+        "architecture": "x86_64",
+        "distribution_release": "noble",
+        "virtualization_type": "none",
+        "interfaces": ["eth0", "lo"],
+        "hostname": "test-host",
+    },
+    "ansible_host": "10.0.0.1",
+    "env": "staging",
+    "environment": "staging",
+    "customer_id": "test",
+    "zitadel_domain": "zitadel.test",
+    "_env_name": "staging",
+    "_observability_data_root": "/opt",
+    "skip_zitadel_stack": False,
+    "skip_htpasswd": False,
+    "skip_observability_stack": False,
+    "backup_enabled": True,
+    "app_filter": "",
+    "app_domain": "test.example.com",
+    "oidc_client_id": "test-client-id",
+    "oidc_client_secret": "test-secret",  # nosec B105 — mock value for Jinja rendering, not a real secret
+    "s3_backup_bucket": "test-bucket",
+    "s3_endpoint": "https://s3.test",
+    "s3_access_key": "test-key",
+    "s3_secret_key": "test-secret",  # nosec B105 — mock value for Jinja rendering, not a real secret
+}
+
+# Pattern to find {{ ... }} expressions (non-greedy, single-line).
+EXPR_PATTERN = re.compile(r"\{\{(.*?)\}\}", re.DOTALL)
+
+
+def _find_yaml_files(path: Path) -> list[Path]:
+    """Find Ansible YAML files (tasks, playbooks, handlers) in a path."""
+    if path.is_file():
+        return [path]
+    files: list[Path] = []
+    for pattern in ["**/*.yml", "**/*.yaml"]:
+        files.extend(path.glob(pattern))
+    # Exclude molecule scenarios — they have their own variables.
+    return [f for f in files if "molecule" not in f.parts]
+
+
+def _extract_expressions(content: str) -> list[str]:
+    """Extract Jinja expressions from file content.
+
+    Filters out Go template syntax (``{{.Field}}``) used in docker
+    inspect --format strings, and single-character fragments from
+    quoted strings that aren't real Jinja expressions.
+    """
+    expressions = []
+    for match in EXPR_PATTERN.finditer(content):
+        raw = match.group(1)
+        # Skip multi-line expressions (often have YAML formatting artifacts).
+        if "\n" in raw:
+            continue
+        expr = raw.strip()
+        # Skip empty, control flow, and single-char fragments.
+        if not expr or expr.startswith("%") or len(expr) <= 1:
+            continue
+        # Skip Go template syntax (docker inspect --format).
+        if expr.startswith(".") or "println" in expr:
+            continue
+        # Skip expressions containing Go template dot-access patterns.
+        if ".State." in expr or ".NetworkSettings." in expr:
+            continue
+        # Skip expressions with unbalanced parens/brackets/braces —
+        # the regex captured only part of a larger expression where
+        # }} appears inside a dict literal (e.g. default({'k': {}})).
+        if expr.count("(") != expr.count(")"):
+            continue
+        if expr.count("{") != expr.count("}"):
+            continue
+        if expr.count("[") != expr.count("]"):
+            continue
+        expressions.append(expr)
+    return expressions
+
+
+def _render_expression(expr: str) -> tuple[bool, str]:
+    """Try to render a Jinja expression. Returns (success, error_msg)."""
+    try:
+        env = Environment(autoescape=False, keep_trailing_newline=True)  # nosec B701 — Ansible Jinja, not web-facing  # noqa: S701
+
+        # Add common Ansible filters so expressions can render.
+        # strftime: Ansible's signature is strftime(string_format, second, utc)
+        # where string_format is the piped value. If the piped value looks like
+        # a number (epoch) and second looks like a format string, the args are
+        # reversed — this is the exact bug from OBL-INFRA-508.
+        def _strftime(string_format: str, second: float | None = None, utc: bool = False) -> str:
+            if isinstance(string_format, (int, float)) and isinstance(second, str) and "%" in second:
+                raise ValueError(  # noqa: TRY301
+                    "Invalid value for epoch value — strftime filter arguments "
+                    "are reversed. The format string must be the piped value: "
+                    "'%format%' | strftime(epoch), not epoch | strftime('%format%')"
+                )
+            return str(string_format)
+
+        env.filters["strftime"] = _strftime
+        env.filters["b64decode"] = lambda x: x
+        env.filters["b64encode"] = lambda x: x
+        env.filters["regex_replace"] = lambda x, pattern, replacement="": x
+        env.filters["int"] = lambda x, default=0: (
+            int(x) if isinstance(x, (int, float, str)) and str(x).lstrip("-").isdigit() else default
+        )
+        env.filters["bool"] = bool
+        env.filters["basename"] = lambda x: str(x).rsplit("/", 1)[-1]
+        env.filters["dirname"] = lambda x: str(x).rsplit("/", 1)[0] if "/" in str(x) else "."
+        env.filters["combine"] = lambda *args, **kwargs: args[0]
+        env.filters["from_json"] = lambda x: x
+        env.filters["to_json"] = lambda x: x
+        env.filters["ternary"] = lambda x, true_val, false_val=None: true_val if x else false_val
+        env.filters["dict2items"] = lambda x: [
+            {"key": k, "value": v} for k, v in (x.items() if isinstance(x, dict) else [])
+        ]
+        env.filters["map"] = lambda x, attribute=None: x
+        env.filters["default"] = lambda x, default_value="", boolean=False: x if x else default_value
+        env.filters["from_yaml"] = lambda x: x
+        env.filters["difference"] = lambda x, y: x
+        env.filters["join"] = lambda x, sep="": sep.join(str(i) for i in (x if isinstance(x, list) else [x]))
+        env.filters["list"] = lambda x: list(x) if isinstance(x, (list, tuple)) else [x]
+        env.filters["length"] = lambda x: len(x) if hasattr(x, "__len__") else 0
+        env.filters["items"] = lambda x: list(x.items()) if isinstance(x, dict) else []
+        env.filters["first"] = lambda x: x[0] if isinstance(x, (list, str)) and x else x
+        env.filters["last"] = lambda x: x[-1] if isinstance(x, (list, str)) and x else x
+        env.filters["upper"] = lambda x: str(x).upper()
+        env.filters["lower"] = lambda x: str(x).lower()
+        env.filters["replace"] = lambda x, old, new: str(x).replace(old, new)
+        env.filters["split"] = lambda x, sep=None: str(x).split(sep) if sep else str(x).split()
+        env.filters["trim"] = lambda x: str(x).strip()
+        env.filters["sort"] = lambda x: sorted(x) if isinstance(x, list) else x
+        env.filters["unique"] = lambda x: list(set(x)) if isinstance(x, list) else x
+        env.filters["count"] = lambda x: len(x) if hasattr(x, "__len__") else 0
+        env.filters["float"] = lambda x, default=0.0: (
+            float(x) if isinstance(x, (int, float, str)) and str(x).replace(".", "").lstrip("-").isdigit() else default
+        )
+        env.filters["string"] = str
+        env.filters["indent"] = lambda x, width=4: str(x)
+        env.filters["to_nice_json"] = str
+        env.filters["to_nice_yaml"] = str
+        env.filters["from_yaml_all"] = lambda x: x
+        env.filters["groupby"] = lambda x: x
+        env.filters["dictsort"] = lambda x: list(x.items()) if isinstance(x, dict) else []
+        env.filters["max"] = lambda x: max(x) if isinstance(x, list) and x else x
+        env.filters["min"] = lambda x: min(x) if isinstance(x, list) and x else x
+        env.filters["reverse"] = lambda x: list(reversed(x)) if isinstance(x, list) else x
+        env.filters["flatten"] = lambda x: x
+        env.filters["product"] = lambda x: x
+        env.filters["zip"] = lambda x: x
+        env.filters["subelements"] = lambda x: x
+        env.filters["json_query"] = lambda x: x
+        env.filters["type_debug"] = lambda x: type(x).__name__
+        env.globals["lookup"] = lambda *args, **kwargs: ""
+        env.globals["query"] = lambda *args, **kwargs: []
+
+        template = env.from_string("{{ " + expr + " }}")
+        result = template.render(**MOCK_CONTEXT)
+    except TemplateSyntaxError as e:
+        return False, f"Syntax error: {e.message}"
+    except UndefinedError as e:
+        # Undefined variable — skip, we can't mock everything.
+        return True, f"Skipped (undefined: {e})"
+    except Exception as e:
+        # Check if it's a filter argument error.
+        error_msg = str(e)
+        if "Invalid value for epoch" in error_msg:
+            return False, f"strftime filter argument error: {error_msg}"
+        # Other errors might be due to missing mock variables — skip.
+        return True, f"Skipped ({type(e).__name__}: {error_msg})"
+    else:
+        return True, result
+
+
+def _check_file(filepath: Path, repo_root: Path) -> list[str]:
+    """Check all Jinja expressions in a file. Returns list of violations."""
+    violations = []
+    content = filepath.read_text()
+    expressions = _extract_expressions(content)
+
+    for expr in expressions:
+        success, msg = _render_expression(expr)
+        if not success:
+            try:
+                rel_path = filepath.relative_to(repo_root)
+            except ValueError:
+                rel_path = filepath
+            violations.append(f"{rel_path}: `{{{{ {expr} }}}}` — {msg}")
+
+    return violations
+
+
+@click.command()
+@click.option(
+    "--path",
+    type=click.Path(exists=True, path_type=Path),
+    help="Check a specific file or directory (default: ansible/playbooks + ansible/roles).",
+)
+@click.option(
+    "--ansible-dir",
+    "ansible_dirs",
+    type=click.Path(exists=True, path_type=Path),
+    multiple=True,
+    default=None,
+    help="Override the default ansible directories (can be repeated). Defaults to ansible/playbooks and ansible/roles.",
+)
+def main(path: Path | None, ansible_dirs: tuple[Path, ...]) -> None:
+    """Validate Jinja2 expressions in Ansible files."""
+    dirs = list(ansible_dirs) if ansible_dirs else _default_ansible_dirs()
+    if path:
+        files = _find_yaml_files(path)
+    else:
+        files: list[Path] = []
+        for d in dirs:
+            files.extend(_find_yaml_files(d))
+
+    all_violations: list[str] = []
+    for f in files:
+        all_violations.extend(_check_file(f, REPO_ROOT))
+
+    if all_violations:
+        click.echo("[check-jinja-expr] FAIL: invalid Jinja expressions found:")
+        for v in all_violations:
+            click.echo(f"  - {v}")
+        click.echo("\nFix: test expressions with `ansible localhost -m debug -a 'msg={{ <expr> }}'`")
+        sys.exit(1)
+    else:
+        click.echo("[check-jinja-expr] OK: all Jinja expressions render correctly.")
+
+
+if __name__ == "__main__":  # pragma: no cover
+    main()

src/devx/tools/check_test_isolation.py

@@ -7,25 +7,48 @@ This module is used in two ways:
    When devx is installed, pytest auto-discovers this plugin via the
    ``pytest11`` entry point.  Every ``pytest`` run statically analyzes
    test files for patterns that cause slow, non-deterministic, or
-   non-hermetic tests and reports violations as warnings.
+   non-hermetic tests and **fails the test run** if any violations are found.
 
-   To promote warnings to errors (fail the test run), add to pyproject.toml::
+   The plugin also wraps ``subprocess.run`` at runtime to catch real
+   subprocess calls that leak through transitive call paths (e.g.
+   ``CliRunner.invoke(main)`` → ``main()`` → ``update_doc_versions()``
+   → ``subprocess.run()``).  If a test spawns a real subprocess without
+   ``@patch``, the test fails.
 
-       [tool.pytest.ini_options]
-       filterwarnings = ["error:Test isolation:UserWarning"]
-
-   Or use the ``--strict-test-isolation`` flag on the command line.
+   To disable for a specific run: ``--no-test-isolation``.
 
 2. **As a standalone CLI** (for CI gates)::
 
        python3 -m devx.tools.check_test_isolation [--test-path tests/]
-       python3 -m devx.tools.check_test_isolation --strict
+
+   Always exits non-zero on any hard violation. Transitive-subprocess
+   findings are reported as advisories (exit 0) since static analysis
+   can't predict early exits — the runtime audit is authoritative.
+
+Project-Specific Configuration
+-------------------------------
+
+Projects can extend the built-in rule sets via ``[tool.devx.check_test_isolation]``
+in ``pyproject.toml``.  Entries are merged on top of the defaults — they
+add to (not replace) the built-in rules::
+
+    [tool.devx.check_test_isolation]
+    # Functions known to do filesystem or network I/O
+    io_functions = { "my_func" = "reads config from disk", ... }
+    # Functions known to spawn subprocesses
+    subprocess_helpers = { "my_helper" = "calls subprocess.run", ... }
+    # Transitive deps: if a helper calls these, patching any of them is safe
+    helper_internal_calls = { "my_helper" = ["subprocess", "run_cmd"], ... }
+    # I/O function internal deps: patching any of these makes the call safe
+    io_internal_calls = { "my_func" = ["open", "yaml"], ... }
+    # Heavy modules slow to import at module level in test files
+    heavy_module_imports = { "mymodule" = 150.0, ... }
 
 Patterns detected:
 
 1. **Unpatched subprocess calls** — test functions that call
    ``subprocess.run/call/Popen/check_call/check_output`` without a
-   corresponding ``@patch`` decorator.
+   corresponding ``@patch`` decorator or ``with patch(...)`` context manager.
 2. **Unpatched ``time.sleep``** — test functions that call ``time.sleep``
    without patching it.
 3. **Unpatched known-subprocess-helpers** — functions known to spawn
@@ -34,27 +57,66 @@ Patterns detected:
    network I/O (e.g. ``get_pat``, ``load_secrets``, ``requests.get``)
    called without patching.
 5. **Excessive iteration loops** — ``for _ in range(N)`` where N > 100.
+6. **Module-level heavy imports** — importing ``httpx``, ``ansible``,
+   etc. at module level in test files slows collection for all tests.
+7. **``importlib.reload`` without cleanup** — reloading a module in a
+   test mutates global state.  Each reload must be paired with a
+   cleanup reload (or wrapped in try/finally) to restore defaults.
+8. **Transitive subprocess leaks** — ``CliRunner.invoke(target)`` where
+   ``target`` transitively calls ``subprocess.run`` without being patched.
+   Detected via static call-graph analysis (warning) AND runtime audit
+   (authoritative — fails the test if a real subprocess runs).
 """
 
 from __future__ import annotations
 
 import ast
+import subprocess  # nosec B404
 import sys
+import threading
 from dataclasses import dataclass, field
 from pathlib import Path
 
 import click
 
+from devx.config import _load_pyproject_devx
 from devx.i18n import _
 
 # ── Configuration ─────────────────────────────────────────────────────────────
 
 DEFAULT_MAX_LOOP_ITERATIONS = 100
 
+# Heavy modules that are slow to import (>50ms).  When imported at module
+# level in a test file, they slow down test collection for ALL tests.
+# Maps module name → approximate import time in milliseconds.
+# NOTE: ``requests`` is excluded because it's a core devx dependency —
+# it's loaded during collection regardless of whether test files import it.
+_DEFAULT_HEAVY_MODULE_IMPORTS: dict[str, float] = {
+    "httpx": 80.0,
+    "aiohttp": 120.0,
+    "docker": 90.0,
+    "kubernetes": 200.0,
+    "boto3": 250.0,
+    "botocore": 200.0,
+    "ansible": 300.0,
+    "molecule": 150.0,
+    "cv2": 400.0,
+    "numpy": 100.0,
+    "pandas": 200.0,
+    "matplotlib": 300.0,
+    "PIL": 80.0,
+    "Pillow": 80.0,
+    "sqlalchemy": 150.0,
+    "django": 200.0,
+    "flask": 80.0,
+    "fastapi": 100.0,
+    "pydantic": 60.0,
+}
+
 # Functions known to spawn subprocesses.  When a test calls any of these
 # without patching them, the real subprocess runs.
 # Maps function name → human-readable description.
-KNOWN_SUBPROCESS_HELPERS: dict[str, str] = {
+_DEFAULT_SUBPROCESS_HELPERS: dict[str, str] = {
     "update_doc_versions": "calls subprocess.run to run check_doc_versions --fix",
     "run_tests": "calls run_cmd to run make lint-ruff and make pytest-cov",
     "run_cmd": "calls subprocess.run for shell commands",
@@ -63,10 +125,12 @@ KNOWN_SUBPROCESS_HELPERS: dict[str, str] = {
 # Functions known to do filesystem or network I/O that should be mocked in tests.
 # Maps function name → description of what I/O it does.
 # If a test calls one of these without a corresponding @patch, it's a violation.
-KNOWN_IO_FUNCTIONS: dict[str, str] = {  # nosec B105 — descriptions, not passwords
+_DEFAULT_IO_FUNCTIONS: dict[str, str] = {  # nosec B105 — descriptions, not passwords
     "get_pat": "reads ZITADEL PAT from filesystem/env (ZitadelAuth._iter_sources)",
     "load_secrets": "reads YAML config file from disk",
     "get_customer_secret": "reads customer-specific config from disk",
+    "get_customer_vm_ip": "queries Hetzner Cloud API for VM IP (network I/O)",
+    "get_observability_vm_ip": "queries Hetzner Cloud API for observability VM IP (network I/O)",
     "requests.get": "performs HTTP GET to a real server",
     "requests.post": "performs HTTP POST to a real server",
     "requests.put": "performs HTTP PUT to a real server",
@@ -80,12 +144,172 @@ KNOWN_IO_FUNCTIONS: dict[str, str] = {  # nosec B105 — descriptions, not passw
 # Transitive dependencies: if a helper calls another helper that is patched,
 # the call is safe.  Maps helper → set of function names it internally calls.
 # If ANY of these are in the test's patches, the helper call is safe.
-HELPER_INTERNAL_CALLS: dict[str, set[str]] = {
+_DEFAULT_HELPER_INTERNAL_CALLS: dict[str, set[str]] = {
     "run_tests": {"run_cmd", "subprocess"},
     "update_doc_versions": {"subprocess"},
     "run_cmd": {"subprocess"},
 }
 
+# I/O function internal dependencies: if a test patches one of these
+# internal dependencies, the I/O function call is considered safe.
+# Maps I/O function name → set of internal function/method names it calls.
+_DEFAULT_IO_INTERNAL_CALLS: dict[str, set[str]] = {
+    "get_customer_vm_ip": {"get_tofu_output", "get_tofu_vm_ip", "subprocess"},
+    "get_observability_vm_ip": {"get_tofu_output", "get_tofu_vm_ip", "subprocess"},
+    "get_pat": {
+        "_iter_sources",
+        "_local_pat_path",
+        "_secrets_path",
+        "_read_secrets_pat",
+        "validate_pat",
+        "ZitadelAuth",
+        "load_secrets",
+        "os.environ",
+    },
+    "load_secrets": {"load_vault_yaml", "REPO_ROOT", "open", "yaml", "safe_load"},
+    "get_customer_secret": {"load_customer_secrets", "load_vault_yaml", "load_secrets", "REPO_ROOT", "open"},
+}
+
+
+def _load_test_isolation_config() -> None:
+    """Merge project-specific rules from ``[tool.devx.check_test_isolation]``.
+
+    Reads from pyproject.toml and merges with defaults. Project-specific
+    entries are added on top of (not replacing) the built-in defaults.
+
+    Supported keys::
+
+        [tool.devx.check_test_isolation]
+        io_functions = { "my_func" = "does network I/O", ... }
+        subprocess_helpers = { "my_helper" = "calls subprocess.run", ... }
+        helper_internal_calls = { "my_helper" = ["subprocess", "run_cmd"], ... }
+        io_internal_calls = { "my_func" = ["open", "yaml"], ... }
+        heavy_module_imports = { "mymodule" = 150.0, ... }
+    """
+    devx_cfg = _load_pyproject_devx()
+    cfg_raw = devx_cfg.get("check_test_isolation", {})
+    if not isinstance(cfg_raw, dict):
+        return
+    cfg: dict[str, object] = cfg_raw  # type: ignore[assignment]
+
+    # io_functions: {name: description}
+    io_extra = cfg.get("io_functions", {})
+    if isinstance(io_extra, dict):
+        for name, desc in io_extra.items():
+            if isinstance(name, str) and isinstance(desc, str):
+                KNOWN_IO_FUNCTIONS[name] = desc
+
+    # subprocess_helpers: {name: description}
+    sp_extra = cfg.get("subprocess_helpers", {})
+    if isinstance(sp_extra, dict):
+        for name, desc in sp_extra.items():
+            if isinstance(name, str) and isinstance(desc, str):
+                KNOWN_SUBPROCESS_HELPERS[name] = desc
+
+    # helper_internal_calls: {name: [deps]}
+    hic_extra = cfg.get("helper_internal_calls", {})
+    if isinstance(hic_extra, dict):
+        for name, deps in hic_extra.items():
+            if isinstance(name, str) and isinstance(deps, list):
+                deps_set = {str(d) for d in deps if isinstance(d, str)}
+                HELPER_INTERNAL_CALLS.setdefault(name, set()).update(deps_set)
+
+    # io_internal_calls: {name: [deps]}
+    iic_extra = cfg.get("io_internal_calls", {})
+    if isinstance(iic_extra, dict):
+        for name, deps in iic_extra.items():
+            if isinstance(name, str) and isinstance(deps, list):
+                deps_set = {str(d) for d in deps if isinstance(d, str)}
+                IO_INTERNAL_CALLS.setdefault(name, set()).update(deps_set)
+
+    # heavy_module_imports: {name: ms}
+    hmi_extra = cfg.get("heavy_module_imports", {})
+    if isinstance(hmi_extra, dict):
+        for name, ms in hmi_extra.items():
+            if isinstance(name, str) and isinstance(ms, (int, float)):
+                HEAVY_MODULE_IMPORTS[name] = float(ms)
+
+
+# Active rule sets — start with defaults, merged with project config at import.
+HEAVY_MODULE_IMPORTS: dict[str, float] = dict(_DEFAULT_HEAVY_MODULE_IMPORTS)
+KNOWN_SUBPROCESS_HELPERS: dict[str, str] = dict(_DEFAULT_SUBPROCESS_HELPERS)
+KNOWN_IO_FUNCTIONS: dict[str, str] = dict(_DEFAULT_IO_FUNCTIONS)
+HELPER_INTERNAL_CALLS: dict[str, set[str]] = {k: set(v) for k, v in _DEFAULT_HELPER_INTERNAL_CALLS.items()}
+IO_INTERNAL_CALLS: dict[str, set[str]] = {k: set(v) for k, v in _DEFAULT_IO_INTERNAL_CALLS.items()}
+
+# Merge project-specific configuration from pyproject.toml
+_load_test_isolation_config()
+
+# subprocess functions that the runtime audit wraps.
+_SUBPROCESS_FUNCS = ("run", "call", "check_call", "check_output", "Popen")
+
+
+# ── Runtime subprocess audit ──────────────────────────────────────────────────
+#
+# The static AST analyzer can only see direct calls in test functions.
+# It cannot trace transitive calls through CliRunner.invoke(main, ...)
+# → main() → update_doc_versions() → subprocess.run().
+#
+# The runtime audit wraps subprocess functions during test execution.
+# If a test does NOT @patch subprocess, the wrapper catches real calls.
+# If a test DOES @patch subprocess, the patch overrides our wrapper
+# (correct — the test is mocking it).
+
+
+class _SubprocessAudit:
+    """Thread-local audit tracker for real subprocess calls during tests."""
+
+    def __init__(self) -> None:
+        self._local = threading.local()
+        self._installed = False
+        self._originals: dict[str, object] = {}
+
+    def _ensure_installed(self) -> None:
+        """Install wrappers on subprocess module (once)."""
+        if self._installed:
+            return
+        for name in _SUBPROCESS_FUNCS:
+            original = getattr(subprocess, name, None)
+            if original is None:
+                continue
+            self._originals[name] = original
+            setattr(subprocess, name, self._make_wrapper(name, original))
+        self._installed = True
+
+    def _make_wrapper(self, name: str, original: object) -> object:
+        """Create a wrapper that records calls when auditing is active."""
+
+        def wrapper(*args: object, **kwargs: object) -> object:
+            calls = getattr(self._local, "calls", None)
+            if calls is not None:
+                # Extract command for diagnostics
+                cmd = args[0] if args else kwargs.get("args", "?")
+                if isinstance(cmd, (list, tuple)) and cmd:
+                    cmd_str = " ".join(str(c) for c in cmd[:4])
+                    if len(cmd) > 4:
+                        cmd_str += " ..."
+                else:
+                    cmd_str = str(cmd)
+                calls.append((name, cmd_str))
+            return original(*args, **kwargs)  # type: ignore[misc]
+
+        return wrapper
+
+    def start_test(self) -> None:
+        """Begin auditing subprocess calls for the current test."""
+        self._ensure_installed()
+        self._local.calls = []
+
+    def stop_test(self) -> list[tuple[str, str]]:
+        """Stop auditing and return recorded calls."""
+        calls = getattr(self._local, "calls", [])
+        self._local.calls = None
+        return calls
+
+
+# Singleton instance used by the pytest plugin
+_audit = _SubprocessAudit()
+
 
 # ── Data structures ───────────────────────────────────────────────────────────
 
@@ -123,22 +347,58 @@ class TestFunctionInfo:
 
 
 def _extract_patch_targets(node: ast.FunctionDef | ast.AsyncFunctionDef | ast.ClassDef) -> set[str]:
-    """Extract @patch targets from decorators on a function or class."""
+    """Extract @patch targets from decorators AND ``with patch(...)`` statements.
+
+    Detects:
+    - ``@patch("module.func")`` decorators
+    - ``with patch("module.func")`` context managers
+    - ``with patch.object(module, "func")`` context managers
+    - ``with patch("a"), patch("b")`` multiple patches
+    """
     targets: set[str] = set()
+
+    def _process_patch_call(call: ast.Call) -> None:
+        """Extract target from a patch() or patch.object() call."""
+        func = call.func
+        # patch("module.func") — either bare `patch(...)` or `mock.patch(...)`
+        if (isinstance(func, ast.Name) and func.id == "patch") or (
+            isinstance(func, ast.Attribute) and func.attr == "patch"
+        ):
+            if call.args and isinstance(call.args[0], ast.Constant) and isinstance(call.args[0].value, str):
+                target = call.args[0].value
+                targets.add(target)
+                targets.add(target.rsplit(".", 1)[-1])
+        # patch.object(module, "func") — extract short name from 2nd arg
+        elif (
+            isinstance(func, ast.Attribute)
+            and func.attr == "object"
+            and isinstance(func.value, ast.Name)
+            and func.value.id == "patch"
+            and len(call.args) >= 2
+            and isinstance(call.args[1], ast.Constant)
+            and isinstance(call.args[1].value, str)
+            and call.args[0]
+            and isinstance(call.args[0], ast.Name)
+        ):
+            short = call.args[1].value
+            targets.add(short)
+            # We can't resolve the module alias here, but the short
+            # name is enough for patch matching in the call graph.
+
+    # 1. Extract from decorators
     for decorator in node.decorator_list:
         if isinstance(decorator, ast.Call):
-            func = decorator.func
-            is_patch = (
-                isinstance(func, ast.Name)
-                and func.id == "patch"
-                or isinstance(func, ast.Attribute)
-                and func.attr == "patch"
-            )
-            if is_patch and decorator.args and isinstance(decorator.args[0], ast.Constant):
-                target = decorator.args[0].value
-                if isinstance(target, str):
-                    targets.add(target)
-                    targets.add(target.rsplit(".", 1)[-1])
+            _process_patch_call(decorator)
+
+    # 2. Extract from `with patch(...)` context managers in the body
+    if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+        for child in ast.walk(node):
+            if isinstance(child, ast.With):
+                for item in child.items:
+                    ctx = item.context_expr
+                    if isinstance(ctx, ast.Call):
+                        _process_patch_call(ctx)
+
     return targets
 
 
@@ -208,19 +468,303 @@ def _get_range_count(node: ast.Call) -> int | None:
     return None  # pragma: no cover
 
 
+# ── Call-graph builder ────────────────────────────────────────────────────────
+#
+# The static AST analyzer can only see direct calls in test functions.
+# It cannot trace transitive calls through CliRunner.invoke(main, ...)
+# → main() → update_doc_versions() → subprocess.run().
+#
+# The call-graph builder parses all source files in the package and builds
+# a map: function_name → set of function_names it calls.
+# When a test calls runner.invoke(target, ...), we trace the call graph
+# from target to find all reachable functions, then check if any of them
+# call subprocess.run (or other dangerous functions) without being patched.
+
+
+# Dangerous functions that should never run in unit tests.
+# Maps full call name → description.
+_DANGEROUS_CALLS: dict[str, str] = {
+    "subprocess.run": "spawns a real subprocess",
+    "subprocess.call": "spawns a real subprocess",
+    "subprocess.check_call": "spawns a real subprocess",
+    "subprocess.check_output": "spawns a real subprocess",
+    "subprocess.Popen": "spawns a real subprocess",
+}
+
+
+@dataclass
+class _FunctionNode:
+    """AST node for a function with its called names."""
+
+    name: str
+    module: str
+    calls: set[str]  # short names of functions called
+    subprocess_calls: set[str]  # dangerous subprocess calls made directly
+    io_calls: set[str]  # known I/O function calls made directly
+
+
+class CallGraph:
+    """Call graph built from source files in a package directory."""
+
+    def __init__(self, src_dir: Path) -> None:
+        self.src_dir = src_dir
+        # Maps "module.func" → _FunctionNode
+        self._nodes: dict[str, _FunctionNode] = {}
+        # Maps short name → list of full names (for resolution)
+        self._by_short: dict[str, list[str]] = {}
+        self._built = False
+
+    def _ensure_built(self) -> None:
+        if self._built:
+            return
+        self._build()
+        self._built = True
+
+    def _build(self) -> None:
+        """Parse all .py files under src_dir and build the call graph."""
+        for py_file in sorted(self.src_dir.rglob("*.py")):
+            try:
+                source = py_file.read_text()
+                tree = ast.parse(source, filename=str(py_file))
+            except (SyntaxError, UnicodeDecodeError):
+                continue
+            # Derive module name from path relative to src_dir
+            rel = py_file.relative_to(self.src_dir)
+            module_parts = list(rel.with_suffix("").parts)
+            if module_parts and module_parts[-1] == "__init__":
+                module_parts = module_parts[:-1]
+            module = ".".join(module_parts)
+            self._scan_module(tree, module)
+
+    def _scan_module(self, tree: ast.Module, module: str) -> None:
+        """Scan a module AST and register all top-level functions.
+
+        Methods defined inside classes are NOT registered — they are called
+        via objects (e.g. ``tea.create_issue()``) and resolving them by short
+        name alone causes false positives when the class is patched (e.g.
+        ``@patch("...TeaCLI")`` mocks all methods).
+        """
+        for node in tree.body:
+            self._scan_node(node, module)
+
+    def _scan_node(self, node: ast.AST, module: str) -> None:
+        """Recursively scan a node, registering non-method functions."""
+        if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            self._register_function(node, module)
+            # Don't recurse into function bodies — nested functions are
+            # not callable by name from outside.
+            return
+        if isinstance(node, ast.ClassDef):
+            # Skip class body — methods are not registered.
+            return
+        # Recurse into other compound statements (if/for/try/with/etc.)
+        for child in ast.iter_child_nodes(node):
+            self._scan_node(child, module)
+
+    def _register_function(self, node: ast.FunctionDef | ast.AsyncFunctionDef, module: str) -> None:
+        """Register a function and its direct calls in the call graph."""
+        full_name = f"{module}.{node.name}"
+        calls: set[str] = set()
+        subprocess_calls: set[str] = set()
+        io_calls: set[str] = set()
+
+        for child in ast.walk(node):
+            if isinstance(child, ast.Call):
+                full = _get_full_called_name(child)
+                short = _get_called_name(child)
+                if short:
+                    calls.add(short)
+                if full and full in _DANGEROUS_CALLS:
+                    subprocess_calls.add(full)
+                if short and short in KNOWN_IO_FUNCTIONS:
+                    io_calls.add(short)
+                # KNOWN_SUBPROCESS_HELPERS are intermediate functions (e.g.
+                # run_tests → run_cmd → subprocess.run).  They are already
+                # in *calls* so the BFS will traverse into them and find the
+                # actual subprocess call.  Adding them to *subprocess_calls*
+                # here would cause false positives when the helper itself is
+                # transitively patched (e.g. run_cmd is patched → run_tests
+                # is safe, but would still be reported).
+
+        fn_node = _FunctionNode(
+            name=node.name,
+            module=module,
+            calls=calls,
+            subprocess_calls=subprocess_calls,
+            io_calls=io_calls,
+        )
+        self._nodes[full_name] = fn_node
+        self._by_short.setdefault(node.name, []).append(full_name)
+
+    def find_reachable_dangerous(
+        self,
+        target_name: str,
+        patches: set[str],
+        max_depth: int = 10,
+        import_map: dict[str, str] | None = None,
+    ) -> list[tuple[str, str]]:
+        """Find all dangerous calls reachable from target_name that aren't patched.
+
+        Returns a list of (function_name, description) tuples for each
+        unpatched dangerous call found in the transitive closure.
+
+        If import_map is provided (mapping short names to fully-qualified
+        module paths), it's used to resolve the target precisely instead
+        of matching by short name alone.
+        """
+        self._ensure_built()
+
+        # Resolve target to full name(s)
+        # First try precise resolution via import_map
+        candidates: list[str] = []
+        if import_map and target_name in import_map:
+            full = import_map[target_name]
+            candidates = [full] if full in self._nodes else self._by_short.get(target_name, [])
+        elif target_name in self._nodes:
+            # Already a fully-qualified name (e.g. devx.tools.build_image.main)
+            candidates = [target_name]
+        else:
+            # Fall back to short name resolution
+            short = target_name.rsplit(".", 1)[-1]
+            candidates = self._by_short.get(short, [])
+
+        if not candidates:
+            return []
+
+        visited: set[str] = set()
+        dangerous: list[tuple[str, str]] = []
+        queue: list[tuple[str, int]] = [(c, 0) for c in candidates]
+
+        while queue:
+            full_name, depth = queue.pop(0)
+            if full_name in visited or depth > max_depth:
+                continue
+            visited.add(full_name)
+
+            node = self._nodes.get(full_name)
+            if node is None:
+                continue
+
+            # Check direct subprocess calls
+            for sc in node.subprocess_calls:
+                short = sc.rsplit(".", 1)[-1]
+                if not self._is_patched(sc, short, patches):
+                    desc = _DANGEROUS_CALLS.get(sc, "")
+                    dangerous.append((full_name, desc))
+
+            # Check direct IO calls
+            for io in node.io_calls:
+                if not self._is_patched(io, io, patches):
+                    desc = KNOWN_IO_FUNCTIONS.get(io, "")
+                    if desc:
+                        dangerous.append((full_name, desc))
+
+            # Enqueue called functions — skip if the called function is patched
+            for called_short in node.calls:
+                if self._is_patched(called_short, called_short, patches):
+                    continue
+                # Prefer same-module resolution, then fall back to short name
+                # only if there's a single global match (avoids false positives
+                # when multiple modules define functions with the same name).
+                same_module = f"{node.module}.{called_short}"
+                if same_module in self._nodes and same_module not in visited:
+                    queue.append((same_module, depth + 1))
+                else:
+                    matches = self._by_short.get(called_short, [])
+                    if len(matches) == 1 and matches[0] not in visited:
+                        queue.append((matches[0], depth + 1))
+
+        return dangerous
+
+    @staticmethod
+    def _is_patched(full: str, short: str, patches: set[str]) -> bool:
+        """Check if a function is covered by the test's @patch set."""
+        if short in patches or full in patches:
+            return True
+        # Check if any patch entry ends with ".short" (e.g. "subprocess.run"
+        # is patched by "devx.ci.release.subprocess.run").  Use exact
+        # endswith, not substring, to avoid "run" matching "run_cmd".
+        return any(p.endswith(f".{short}") or p == full for p in patches)
+
+
 # ── Analyzers ─────────────────────────────────────────────────────────────────
 
 
 class TestIsolationVisitor(ast.NodeVisitor):
     """AST visitor that detects un-hermetic test patterns."""
 
-    def __init__(self, file_path: Path, max_loop_iterations: int = DEFAULT_MAX_LOOP_ITERATIONS):
+    def __init__(
+        self,
+        file_path: Path,
+        max_loop_iterations: int = DEFAULT_MAX_LOOP_ITERATIONS,
+        call_graph: CallGraph | None = None,
+    ):
         self.file_path = file_path
         self.max_loop_iterations = max_loop_iterations
+        self.call_graph = call_graph
         self.violations: list[Violation] = []
         self._current_function: TestFunctionInfo | None = None
         self._current_class_patches: set[str] = set()
         self._in_test_class = False
+        self._reload_calls: list[tuple[int, str | None]] = []
+        # Import map: short name → fully-qualified module.func
+        # e.g. {"main": "devx.ci.release.main"} for `from devx.ci.release import main`
+        self._import_map: dict[str, str] = {}
+
+    def visit_Import(self, node: ast.Import) -> None:
+        # Track imports for call-graph resolution
+        if self._current_function is None:
+            for alias in node.names:
+                name = alias.asname or alias.name
+                self._import_map[name] = alias.name
+        # Check for heavy module imports
+        if self._current_function is None:
+            for alias in node.names:
+                mod = alias.name.split(".")[0]
+                if mod in HEAVY_MODULE_IMPORTS:
+                    self.violations.append(
+                        Violation(
+                            file=self.file_path,
+                            line=node.lineno,
+                            col=node.col_offset,
+                            category="heavy-module-import",
+                            message=_(
+                                "Heavy import '{mod}' (~{ms:.0f}ms) at module level — "
+                                "this slows test collection for all tests. "
+                                "Move inside test functions or use lazy import.",
+                                mod=alias.name,
+                                ms=HEAVY_MODULE_IMPORTS[mod],
+                            ),
+                        )
+                    )
+        self.generic_visit(node)
+
+    def visit_ImportFrom(self, node: ast.ImportFrom) -> None:
+        # Track imports for call-graph resolution
+        if self._current_function is None and node.module:
+            for alias in node.names:
+                name = alias.asname or alias.name
+                self._import_map[name] = f"{node.module}.{alias.name}"
+        # Check for heavy module imports
+        if self._current_function is None and node.module:
+            mod = node.module.split(".")[0]
+            if mod in HEAVY_MODULE_IMPORTS:
+                self.violations.append(
+                    Violation(
+                        file=self.file_path,
+                        line=node.lineno,
+                        col=node.col_offset,
+                        category="heavy-module-import",
+                        message=_(
+                            "Heavy import '{mod}' (~{ms:.0f}ms) at module level — "
+                            "this slows test collection for all tests. "
+                            "Move inside test functions or use lazy import.",
+                            mod=node.module,
+                            ms=HEAVY_MODULE_IMPORTS[mod],
+                        ),
+                    )
+                )
+        self.generic_visit(node)
 
     def visit_ClassDef(self, node: ast.ClassDef) -> None:
         old_class_patches = self._current_class_patches
@@ -256,9 +800,33 @@ class TestIsolationVisitor(ast.NodeVisitor):
             is_test=True,
         )
         old_func = self._current_function
+        old_reloads = self._reload_calls
         self._current_function = info
+        self._reload_calls = []
         self.generic_visit(node)
+        # Check 7: importlib.reload without cleanup
+        # Each reload mutates global module state.  An odd number of
+        # reloads means the module is left in a modified state.
+        if len(self._reload_calls) % 2 != 0:
+            first_line, mod_name = self._reload_calls[0]
+            self.violations.append(
+                Violation(
+                    file=self.file_path,
+                    line=first_line,
+                    col=0,
+                    category="reload-without-cleanup",
+                    message=_(
+                        "importlib.reload({mod}) called {n} time(s) in test '{test}' — "
+                        "odd count leaves module in modified state. "
+                        "Add a final reload to restore defaults or wrap in try/finally.",
+                        mod=mod_name or "module",
+                        n=len(self._reload_calls),
+                        test=info.name,
+                    ),
+                )
+            )
         self._current_function = old_func
+        self._reload_calls = old_reloads
 
     def visit_Call(self, node: ast.Call) -> None:
         if self._current_function is None:
@@ -269,6 +837,16 @@ class TestIsolationVisitor(ast.NodeVisitor):
         short_name = _get_called_name(node)
         all_patches = self._current_function.patches | self._current_function.class_patches
 
+        # Track importlib.reload calls for cleanup check
+        if full_name == "importlib.reload" or (short_name == "reload" and "reload" in all_patches):
+            mod_arg = node.args[0] if node.args else None
+            mod_name = None
+            if isinstance(mod_arg, ast.Name):
+                mod_name = mod_arg.id
+            elif isinstance(mod_arg, ast.Attribute):
+                mod_name = mod_arg.attr
+            self._reload_calls.append((node.lineno, mod_name))
+
         # Check 1: subprocess.run / subprocess.call / subprocess.Popen etc.
         if full_name and full_name.startswith("subprocess."):
             method = full_name.split(".", 1)[1]
@@ -349,6 +927,9 @@ class TestIsolationVisitor(ast.NodeVisitor):
             or sn in all_patches
             or any(io_key in p or sn in p for p in all_patches)
             or any(p.endswith(f".{sn}") for p in all_patches)
+            or any(
+                dep in all_patches or any(dep in p for p in all_patches) for dep in IO_INTERNAL_CALLS.get(io_key, set())
+            )
         ):
             self.violations.append(
                 Violation(
@@ -366,6 +947,52 @@ class TestIsolationVisitor(ast.NodeVisitor):
                 )
             )
 
+        # Check 8: CliRunner.invoke / runner.invoke — trace call graph
+        # Detect runner.invoke(target, ...) or CliRunner().invoke(target, ...)
+        if short_name == "invoke" and self.call_graph is not None and node.args:
+            target = node.args[0]
+            target_name: str | None = None
+            if isinstance(target, ast.Name):
+                target_name = target.id
+            elif isinstance(target, ast.Attribute):
+                # Handle module.func pattern (e.g. build_image.main)
+                # Resolve module prefix via import_map
+                if isinstance(target.value, ast.Name):
+                    mod_short = target.value.id
+                    mod_full = self._import_map.get(mod_short)
+                    target_name = f"{mod_full}.{target.attr}" if mod_full else target.attr
+                else:
+                    target_name = target.attr
+            if target_name:
+                dangerous = self.call_graph.find_reachable_dangerous(
+                    target_name, all_patches, import_map=self._import_map
+                )
+                if dangerous:
+                    # Deduplicate by function name
+                    seen: set[str] = set()
+                    unique: list[tuple[str, str]] = []
+                    for func, desc in dangerous:
+                        if func not in seen:
+                            seen.add(func)
+                            unique.append((func, desc))
+                    funcs_desc = "; ".join(f"{f} ({d})" for f, d in unique[:3])
+                    self.violations.append(
+                        Violation(
+                            file=self.file_path,
+                            line=node.lineno,
+                            col=node.col_offset,
+                            category="transitive-subprocess",
+                            message=_(
+                                "CliRunner.invoke({target}) in test '{test}' reaches "
+                                "unpatched dangerous functions: {funcs}. "
+                                "Add @patch for each or patch the calling function.",
+                                target=target_name,
+                                test=self._current_function.name,
+                                funcs=funcs_desc,
+                            ),
+                        )
+                    )
+
         self.generic_visit(node)
 
     def visit_For(self, node: ast.For) -> None:
@@ -400,7 +1027,11 @@ def find_test_files(test_path: Path) -> list[Path]:
     return sorted(test_path.rglob("test_*.py"))
 
 
-def analyze_file(file_path: Path, max_loop_iterations: int = DEFAULT_MAX_LOOP_ITERATIONS) -> list[Violation]:
+def analyze_file(
+    file_path: Path,
+    max_loop_iterations: int = DEFAULT_MAX_LOOP_ITERATIONS,
+    call_graph: CallGraph | None = None,
+) -> list[Violation]:
     """Analyze a single test file for isolation violations.
 
     Files in ``integration/`` directories are skipped — integration tests
@@ -422,7 +1053,7 @@ def analyze_file(file_path: Path, max_loop_iterations: int = DEFAULT_MAX_LOOP_IT
             )
         ]
 
-    visitor = TestIsolationVisitor(file_path, max_loop_iterations)
+    visitor = TestIsolationVisitor(file_path, max_loop_iterations, call_graph)
     visitor.visit(tree)
     return visitor.violations
 
@@ -431,12 +1062,13 @@ def analyze_test_files(
     test_path: Path,
     max_loop_iterations: int = DEFAULT_MAX_LOOP_ITERATIONS,
     categories: set[str] | None = None,
+    call_graph: CallGraph | None = None,
 ) -> list[Violation]:
     """Analyze all test files under test_path. Returns list of violations."""
     test_files = find_test_files(test_path)
     all_violations: list[Violation] = []
     for file_path in test_files:
-        violations = analyze_file(file_path, max_loop_iterations)
+        violations = analyze_file(file_path, max_loop_iterations, call_graph)
         if categories:
             violations = [v for v in violations if v.category in categories]
         all_violations.extend(violations)
@@ -447,23 +1079,17 @@ def analyze_test_files(
 #
 # When devx is installed, pytest auto-discovers this plugin via the
 # `pytest11` entry point.  The plugin runs static analysis on every
-# test file during collection and emits warnings for violations.
-# Use --strict-test-isolation to promote warnings to errors.
+# test file during collection and **fails** on any violation.
+# It also wraps subprocess at runtime to catch transitive leaks.
 
 
 def pytest_addoption(parser):  # type: ignore[no-untyped-def]  # pragma: no cover
     """Register pytest command-line options."""
-    parser.addoption(
-        "--strict-test-isolation",
-        action="store_true",
-        default=False,
-        help="Fail the test run if any test isolation violations are found.",
-    )
     parser.addoption(
         "--no-test-isolation",
         action="store_true",
         default=False,
-        help="Disable test isolation static analysis.",
+        help="Disable test isolation static analysis and runtime subprocess audit.",
     )
     parser.addoption(
         "--test-isolation-max-loop",
@@ -474,46 +1100,129 @@ def pytest_addoption(parser):  # type: ignore[no-untyped-def]  # pragma: no cove
 
 
 def pytest_collection_finish(session):  # type: ignore[no-untyped-def]  # pragma: no cover
-    """Run static analysis after all test files are collected."""
+    """Run static analysis after all test files are collected. Always strict."""
     if session.config.getoption("--no-test-isolation"):
         return
 
-    strict = session.config.getoption("--strict-test-isolation")
     max_loop = session.config.getoption("--test-isolation-max-loop")
 
-    # Analyze all collected test files
+    # Build call graph from source directory for transitive analysis
+    call_graph: CallGraph | None = None
+    for item in session.items:
+        fspath = Path(str(item.fspath))
+        for parent in fspath.parents:
+            src_dir = parent / "src"
+            if src_dir.is_dir():
+                call_graph = CallGraph(src_dir)
+                break
+        if call_graph is not None:
+            break
+
     test_files: set[Path] = set()
     for item in session.items:
         test_files.add(Path(str(item.fspath)))
 
     all_violations: list[Violation] = []
     for file_path in sorted(test_files):
-        violations = analyze_file(file_path, max_loop)
+        violations = analyze_file(file_path, max_loop, call_graph)
         all_violations.extend(violations)
 
     if not all_violations:
         return
 
-    # Emit warnings
-    import warnings
+    # transitive-subprocess is advisory (static can't predict early exits).
+    # All other categories are hard errors.
+    errors = [v for v in all_violations if v.category != "transitive-subprocess"]
+    transitive = [v for v in all_violations if v.category == "transitive-subprocess"]
 
-    for v in sorted(all_violations, key=lambda x: (str(x.file), x.line)):
-        msg = f"Test isolation violation: {v.format()}"
-        warnings.warn(msg, UserWarning, stacklevel=2)
-
-    if strict:
-        count = len(all_violations)
-        files = len({v.file for v in all_violations})
+    if errors:
+        count = len(errors)
+        files = len({v.file for v in errors})
         click.echo(
             _(
-                "\nTest isolation check FAILED: {count} violation(s) in {files} file(s).\n"
-                "Fix: add @patch decorators for subprocess/time.sleep calls, "
-                "or patch the calling function.\n",
+                "\nTest isolation check FAILED: {count} violation(s) in {files} file(s).\n",
                 count=count,
                 files=files,
             ),
             err=True,
         )
+        for v in sorted(errors, key=lambda x: (str(x.file), x.line)):
+            click.echo(f"  {v.format()}", err=True)
+        click.echo(
+            _(
+                "Fix: add @patch decorators or with patch() context managers "
+                "for subprocess/time.sleep calls, or patch the calling function.\n"
+            ),
+            err=True,
+        )
+        import pytest
+
+        pytest.fail(
+            f"Test isolation: {count} violation(s) found. See output above.",
+            pytrace=False,
+        )
+
+    # transitive-subprocess warnings are advisory — runtime audit is authoritative
+    if transitive:
+        import warnings
+
+        for v in sorted(transitive, key=lambda x: (str(x.file), x.line)):
+            msg = f"Test isolation advisory: {v.format()}"
+            warnings.warn(msg, UserWarning, stacklevel=2)
+
+
+# ── Runtime subprocess audit hooks ────────────────────────────────────────────
+
+
+def _is_integration_test(item: object) -> bool:
+    """Check if a test item is an integration test."""
+    markers = getattr(item, "keywords", {})
+    if "integration" in markers:
+        return True
+    fspath = str(getattr(item, "fspath", ""))
+    return "integration" in fspath
+
+
+def pytest_runtest_setup(item: object) -> None:  # type: ignore[no-untyped-def]  # pragma: no cover
+    """Start subprocess audit for non-integration tests."""
+    config = getattr(item, "config", None)
+    if config is None:
+        return
+    if config.getoption("--no-test-isolation"):
+        return
+    if _is_integration_test(item):
+        return
+    _audit.start_test()
+
+
+def pytest_runtest_teardown(item: object, nextitem: object) -> None:  # type: ignore[no-untyped-def]  # pragma: no cover
+    """Fail test if real subprocess calls were made without @patch."""
+    config = getattr(item, "config", None)
+    if config is None:
+        return
+    if config.getoption("--no-test-isolation"):
+        return
+    if _is_integration_test(item):
+        return
+    calls = _audit.stop_test()
+    if not calls:
+        return
+
+    test_name = getattr(item, "name", str(item))
+    lines = [
+        _(
+            "Real subprocess call(s) detected in test '{test}' without @patch:",
+            test=test_name,
+        )
+    ]
+    for func_name, cmd in calls:
+        lines.append(f"  {func_name}({cmd})")
+    lines.append(_('Add @patch("subprocess.run") or patch the calling function to fix this.'))
+    msg = "\n".join(lines)
+
+    import pytest
+
+    pytest.fail(msg, pytrace=False)
 
 
 # ── Standalone CLI ────────────────────────────────────────────────────────────
@@ -536,59 +1245,103 @@ def pytest_collection_finish(session):  # type: ignore[no-untyped-def]  # pragma
     show_default=True,
     help="Maximum allowed iterations in a single test loop.",
 )
-@click.option(
-    "--strict",
-    is_flag=True,
-    default=False,
-    help="Treat warnings as errors (non-zero exit on any violation).",
-)
 @click.option(
     "--categories",
     type=str,
     default="",
     help="Comma-separated list of categories to check (default: all). "
-    "Available: unpatched-subprocess, unpatched-sleep, unpatched-helper, excessive-iterations",
+    "Available: unpatched-subprocess, unpatched-sleep, unpatched-helper, "
+    "excessive-iterations, heavy-module-import, reload-without-cleanup, "
+    "transitive-subprocess",
 )
-def cli(test_paths: tuple[Path, ...], max_loop_iterations: int, strict: bool, categories: str) -> None:
-    """Check test files for un-hermetic patterns that cause slow or flaky tests."""
+@click.option(
+    "--src-dir",
+    type=click.Path(exists=True, file_okay=False, path_type=Path),
+    default=None,
+    help="Source directory for call-graph analysis (auto-detected if omitted).",
+)
+def cli(
+    test_paths: tuple[Path, ...],
+    max_loop_iterations: int,
+    categories: str,
+    src_dir: Path | None,
+) -> None:
+    """Check test files for un-hermetic patterns that cause slow or flaky tests.
+
+    Always exits non-zero on any hard violation. Transitive-subprocess
+    findings are reported as advisories (exit 0) since static analysis
+    can't predict early exits — the runtime audit is authoritative.
+    """
     allowed: set[str] | None = None
     if categories:
         allowed = {c.strip() for c in categories.split(",")}
 
+    # Build call graph for transitive subprocess detection
+    call_graph: CallGraph | None = None
+    if src_dir is not None:
+        call_graph = CallGraph(src_dir)
+    else:
+        for tp in test_paths:
+            for parent in Path(tp).resolve().parents:
+                candidate = parent / "src"
+                if candidate.is_dir():
+                    call_graph = CallGraph(candidate)
+                    break
+            if call_graph is not None:
+                break
+
     all_violations: list[Violation] = []
     total_files = 0
     for test_path in test_paths:
-        violations = analyze_test_files(test_path, max_loop_iterations, allowed)
+        violations = analyze_test_files(test_path, max_loop_iterations, allowed, call_graph)
         all_violations.extend(violations)
         total_files += len(find_test_files(test_path))
 
-    if not all_violations:
+    errors = [v for v in all_violations if v.category != "transitive-subprocess"]
+    advisories = [v for v in all_violations if v.category == "transitive-subprocess"]
+
+    if not errors and not advisories:
         click.echo(
             _("Test isolation check passed: {count} test files analyzed, no violations found.", count=total_files)
         )
         sys.exit(0)
 
-    click.echo(
-        _(
-            "Test isolation check FAILED: {count} violation(s) found in {files} test file(s).",
-            count=len(all_violations),
-            files=len({v.file for v in all_violations}),
-        ),
-        err=True,
-    )
-    click.echo("")
-    for v in sorted(all_violations, key=lambda x: (str(x.file), x.line)):
-        click.echo(f"  {v.format()}", err=True)
+    if errors:
+        click.echo(
+            _(
+                "Test isolation check FAILED: {count} violation(s) in {files} file(s).",
+                count=len(errors),
+                files=len({v.file for v in errors}),
+            ),
+            err=True,
+        )
+        click.echo("")
+        for v in sorted(errors, key=lambda x: (str(x.file), x.line)):
+            click.echo(f"  {v.format()}", err=True)
+        click.echo("")
+        click.echo(
+            _(
+                "Fix: add @patch decorators or with patch() context managers "
+                "for subprocess/time.sleep calls, or patch the calling function."
+            ),
+            err=True,
+        )
+        sys.exit(1)
 
-    click.echo("")
+    # Advisories only — exit 0 but print them
     click.echo(
         _(
-            "Fix: add @patch decorators for subprocess/time.sleep calls, "
-            "or patch the calling function. Use property-based testing for statistical tests."
-        ),
-        err=True,
+            "Test isolation check passed with {count} advisory warning(s) in {files} file(s).",
+            count=len(advisories),
+            files=len({v.file for v in advisories}),
+        )
     )
-    sys.exit(1)
+    click.echo(_("Transitive-subprocess advisories (runtime audit is authoritative):"))
+    for v in sorted(advisories, key=lambda x: (str(x.file), x.line))[:10]:
+        click.echo(f"  {v.format()}")
+    if len(advisories) > 10:
+        click.echo(f"  ... and {len(advisories) - 10} more")
+    sys.exit(0)
 
 
 if __name__ == "__main__":  # pragma: no cover

src/devx/tools/check_test_speed.py

@@ -11,6 +11,18 @@ Usage:
 The module runs ``make test-unit`` with ``PYTEST_ADDOPTS=--durations=0`` so
 that pytest emits per-test timing lines alongside the summary.  Both the
 total wall-clock time and individual test durations are parsed and validated.
+
+CI runner scaling
+-----------------
+CI runners (Gitea Actions Docker containers) are typically 5-8x slower than
+local development machines due to shared CPU, fewer cores, and container
+overhead.  When the ``CI`` environment variable is set (standard CI
+convention), both the total and per-test limits are multiplied by
+``CI_SCALE_FACTOR`` (default 6) to account for this.  This keeps the local
+budget strict while preventing false failures on slower CI runners.
+
+The scale factor can be overridden via the ``DEVX_CI_SCALE_FACTOR``
+environment variable.
 """
 
 from __future__ import annotations
@@ -27,6 +39,12 @@ DEFAULT_MAX_SECONDS = 10.0
 DEFAULT_MAX_SINGLE_SECONDS = 0.5
 TEST_COMMAND = ["make", "test-unit"]
 
+# CI runners are typically 5-8x slower than local machines (shared CPU,
+# fewer cores, container overhead).  Scale limits up when running on CI
+# so the gate catches real regressions, not infrastructure slowness.
+CI_SCALE_FACTOR = float(os.environ.get("DEVX_CI_SCALE_FACTOR", "6"))
+_IS_CI = bool(os.environ.get("CI") or os.environ.get("GITEA_ACTIONS"))
+
 # Matches pytest summary line: "234 passed in 0.70s"
 _TIMING_RE = re.compile(r"(\d+) passed.* in ([0-9.]+)s")
 
@@ -38,6 +56,13 @@ _TIMING_RE = re.compile(r"(\d+) passed.* in ([0-9.]+)s")
 _DURATION_LINE_RE = re.compile(r"^(\d+\.?\d*)s\s+call\s+(.+)$")
 
 
+def _ci_scale_limit(limit: float) -> float:
+    """Scale a time limit by the CI factor when running on CI."""
+    if _IS_CI:
+        return limit * CI_SCALE_FACTOR
+    return limit
+
+
 def run_tests() -> tuple[str, str]:
     """Execute the unit-test suite and return (stdout, stderr).
 
@@ -123,21 +148,38 @@ def check_per_test_speed(
 
 def main(max_seconds: float, max_single_seconds: float) -> None:
     """Run tests, parse timings, and enforce both budgets."""
+    # Scale limits for CI runners (slower CPU, fewer workers).
+    effective_max = _ci_scale_limit(max_seconds)
+    effective_single = _ci_scale_limit(max_single_seconds)
+
+    if _IS_CI:
+        click.echo(
+            _(
+                "[check-test-speed] CI environment detected — scaling limits by {factor}x "
+                "(total: {orig}s → {eff}s, per-test: {orig_s}s → {eff_s}s)",
+                factor=CI_SCALE_FACTOR,
+                orig=max_seconds,
+                eff=effective_max,
+                orig_s=max_single_seconds,
+                eff_s=effective_single,
+            )
+        )
+
     stdout, stderr = run_tests()
     combined = stdout + "\n" + stderr
     click.echo(combined, err=False)
 
     duration = parse_duration(combined)
-    check_speed(duration, max_seconds)
+    check_speed(duration, effective_max)
 
-    if max_single_seconds > 0:
+    if effective_single > 0:
         per_test = parse_per_test_durations(combined)
-        violations = check_per_test_speed(per_test, max_single_seconds)
+        violations = check_per_test_speed(per_test, effective_single)
         if violations:
             msg = _(
                 "Per-test speed check FAILED: {count} test(s) exceed {limit}s limit.",
                 count=len(violations),
-                limit=max_single_seconds,
+                limit=effective_single,
             )
             click.echo(f"\n{msg}", err=True)
             for v in violations:
@@ -148,8 +190,8 @@ def main(max_seconds: float, max_single_seconds: float) -> None:
         _(
             "Unit tests passed in {duration:.2f}s (under {max}s limit, all tests under {single}s per-test limit).",
             duration=duration,
-            max=max_seconds,
-            single=max_single_seconds,
+            max=effective_max,
+            single=effective_single,
         )
     )
 

src/devx/tools/clean_images.py

@@ -5,6 +5,13 @@ Queries the Gitea API for all versions of a package (container type) and
 deletes all but the most recent N versions.  The ``latest`` tag is always
 preserved if present.
 
+.. note::
+    This tool only deletes package versions via the Gitea API. The underlying
+    blob files on the Gitea server's filesystem are NOT removed by this tool
+    (Gitea 1.26.x has no built-in garbage collection). The production VM's
+    daily cleanup script (``cleanup_gitea.py``) handles filesystem blob GC
+    by querying the database for referenced blobs and removing orphaned files.
+
 Usage::
 
     # Clean up ci-base images, keep last 2 versions
@@ -57,7 +64,10 @@ def list_package_versions(
     Returns a list of version dicts, each containing at least ``version``
     and ``created_at`` fields.
     """
-    url = f"{api_url}/packages/{owner}?type=container&name={name}"
+    from urllib.parse import quote
+
+    encoded_name = quote(name, safe="")
+    url = f"{api_url}/packages/{owner}?type=container&name={encoded_name}"
     headers = {"Authorization": f"token {token}"}
     all_versions: list[dict[str, Any]] = []
     page = 1
@@ -96,7 +106,11 @@ def delete_package_version(
 
     Returns True on success, False on failure.
     """
-    url = f"{api_url}/packages/{owner}/{package_type}/{name}/{version}"
+    from urllib.parse import quote
+
+    encoded_name = quote(name, safe="")
+    encoded_version = quote(version, safe="")
+    url = f"{api_url}/packages/{owner}/{package_type}/{encoded_name}/{encoded_version}"
     headers = {"Authorization": f"token {token}"}
     for attempt in range(max_retries):
         try:

src/devx/tools/install_tools.py

@@ -8,6 +8,7 @@ Handles installation of:
 - tea (Gitea CLI — official command-line tool for Gitea API operations)
 - hadolint (Dockerfile linter)
 - vale (prose linter for documentation quality)
+- promtool (Prometheus rule validator)
 
 Each tool is installed to ``~/.local/bin`` if not already on PATH.
 Idempotent: skips tools that are already available.
@@ -47,6 +48,8 @@ TOFU_VERSION = "1.12.3"
 
 VALE_VERSION = "3.15.1"
 
+PROMTOOL_VERSION = "3.5.5"
+
 
 def _arch() -> str:
     """Return the architecture string used by release assets (delegates to shared utility)."""
@@ -62,8 +65,33 @@ def _ensure_target_dir() -> Path:
 
 
 def _download(url: str, dest: Path) -> None:
-    """Download a file from ``url`` to ``dest``."""
-    urllib.request.urlretrieve(url, dest)  # nosec B310
+    """Download a file from ``url`` to ``dest`` with a 60s timeout.
+
+    A User-Agent header is set because some CDNs (e.g. dl.gitea.com)
+    return 403 to requests with Python's default User-Agent.
+    """
+    req = urllib.request.Request(url, headers={"User-Agent": "devx/install-tools"})
+    with urllib.request.urlopen(req, timeout=60) as resp, open(dest, "wb") as f:  # nosec B310
+        shutil.copyfileobj(resp, f)
+
+
+def _download_with_fallback(urls: list[str], binary_name: str) -> Path:
+    """Try downloading a binary from a list of URLs, falling back on failure.
+
+    Returns the path to the installed binary. Raises if all URLs fail.
+    """
+    target_dir = _ensure_target_dir()
+    dest = target_dir / binary_name
+    errors: list[str] = []
+    for url in urls:
+        try:
+            _download(url, dest)
+            dest.chmod(0o755)
+            return dest
+        except Exception as exc:  # noqa: BLE001
+            errors.append(f"{url}: {exc}")
+            click.echo(f"  {binary_name}: retrying — {exc}")
+    raise click.ClickException(f"Failed to download {binary_name} from all URLs: {'; '.join(errors)}")
 
 
 def _download_and_extract_tarball(url: str, binary_name: str) -> Path:
@@ -160,8 +188,13 @@ def install_tea() -> bool:
         click.echo("tea: already installed")
         return True
     arch = _arch()
-    url = f"https://dl.gitea.com/tea/{TEA_VERSION}/tea-{TEA_VERSION}-linux-{arch}"
-    dest = _download_binary(url, "tea")
+    # dl.gitea.com is the primary CDN, but it can return 403 from some networks.
+    # Fall back to the gitea.com release downloads URL.
+    urls = [
+        f"https://dl.gitea.com/tea/{TEA_VERSION}/tea-{TEA_VERSION}-linux-{arch}",
+        f"https://gitea.com/gitea/tea/releases/download/v{TEA_VERSION}/tea-{TEA_VERSION}-linux-{arch}",
+    ]
+    dest = _download_with_fallback(urls, "tea")
     click.echo(f"tea: installed to {dest}")
     return True
 
@@ -212,7 +245,26 @@ def install_vale() -> bool:
     return True
 
 
-TOOL_NAMES = ["actionlint", "git-cliff", "act_runner", "tea", "hadolint", "tofu", "vale"]
+def install_promtool() -> bool:
+    """Install promtool (Prometheus rule validator) if not already present.
+
+    Downloads the official Prometheus release tarball from GitHub and
+    extracts the ``promtool`` binary to ``~/.local/bin``.
+    """
+    if _is_installed("promtool"):
+        click.echo("promtool: already installed")
+        return True
+    arch = _arch()
+    url = (
+        f"https://github.com/prometheus/prometheus/releases/download/"
+        f"v{PROMTOOL_VERSION}/prometheus-{PROMTOOL_VERSION}.linux-{arch}.tar.gz"
+    )
+    dest = _download_and_extract_tarball(url, "promtool")
+    click.echo(f"promtool: installed to {dest}")
+    return True
+
+
+TOOL_NAMES = ["actionlint", "git-cliff", "act_runner", "tea", "hadolint", "tofu", "vale", "promtool"]
 
 
 def _install_tool(name: str) -> bool:
@@ -231,6 +283,8 @@ def _install_tool(name: str) -> bool:
         return install_tofu()
     if name == "vale":
         return install_vale()
+    if name == "promtool":
+        return install_promtool()
     raise click.ClickException(f"Unknown tool: {name}")
 
 

src/devx/tools/setup.py

@@ -15,6 +15,7 @@ from pathlib import Path
 
 import click
 from dotenv import load_dotenv  # pyright: ignore[reportMissingImports,reportUnknownVariableType]
+from tenacity import retry, stop_after_attempt, wait_exponential
 
 from devx.tokens import get_developer_token
 
@@ -56,13 +57,22 @@ def _install_pre_commit_hooks(bin_dir: str) -> None:
 
 
 def _install_ansible_collections(bin_dir: str) -> None:
-    """Install required Ansible Galaxy collections if requirements exist."""
+    """Install required Ansible Galaxy collections if requirements exist.
+
+    Retries up to 3 times with exponential backoff to handle transient
+    network timeouts when contacting galaxy.ansible.com.
+    """
     galaxy = shutil.which("ansible-galaxy") or str(Path(bin_dir) / "ansible-galaxy")
     requirements = Path("ansible/requirements.yml")
     if not requirements.exists():
         click.echo("  ansible/requirements.yml not found — skipping collections.")
         return
-    _run([galaxy, "collection", "install", "-r", str(requirements)])
+
+    @retry(stop=stop_after_attempt(3), wait=wait_exponential(multiplier=2, min=2, max=10), reraise=True)
+    def _do_install() -> None:
+        _run([galaxy, "collection", "install", "-r", str(requirements)])
+
+    _do_install()
 
 
 def _configure_tea_login() -> None:

src/devx/tools/setup_image.py

@@ -64,9 +64,11 @@ def _install_in_image(
     link.symlink_to(opt_venv)
 
     # Build pip install command
+    # --no-deps: the CI image already has all dependencies pre-installed.
+    # We only need to install the project itself in editable mode.
     spec = f".[{extras}]" if extras else "."
     pip_bin = str(Path(venv_link) / "bin" / "pip")
-    cmd = [pip_bin, "install", "--no-cache-dir", "-e", spec]
+    cmd = [pip_bin, "install", "--no-cache-dir", "--no-deps", "-e", spec]
 
     env = os.environ.copy()
     try:
@@ -81,6 +83,17 @@ def _install_in_image(
             username,
             token,
         )
+        # Configure git URL rewrite so git+https dependencies can authenticate
+        subprocess.run(  # nosec B603, B607
+            [
+                "git",
+                "config",
+                "--global",
+                f"url.https://{username}:{token}@{gitea_host}/.insteadOf",
+                f"https://{gitea_host}/",
+            ],
+            check=True,
+        )
 
     click.echo(f"[setup-image] Linked {opt_venv}" + (f" with [{extras}]" if extras else "") + ".")
     subprocess.run(cmd, check=True, env=env)  # nosec B603

src/devx/utils/api.py

@@ -1,14 +1,26 @@
 #!/usr/bin/env python3
-"""Utilities for handling API response values.
+"""Utilities for handling API response values and base HTTP API client.
 
-Many APIs return boolean values as strings (``"true"``, ``"false"``)
-rather than native JSON booleans.  The Mattermost ``/api/v4/config/client``
-endpoint is a notable example.  These helpers handle both string and
-boolean responses safely.
+This module provides two categories of utilities:
+
+1. **Response helpers** — :func:`is_truthy` and :func:`is_falsy` handle
+   APIs that return boolean values as strings (``"true"``, ``"false"``)
+   rather than native JSON booleans.
+
+2. **Base API client** — :class:`APIClient` provides a reusable base
+   class for HTTP API clients with consistent timeout handling, header
+   propagation, and automatic raising on 4xx/5xx responses.
 
 Usage::
 
-    from devx.utils.api import is_truthy, is_falsy
+    from devx.utils.api import APIClient, is_truthy
+
+    class MyClient(APIClient):
+        def __init__(self):
+            super().__init__(
+                base_url="https://api.example.com",
+                headers={"Authorization": "Bearer token"},
+            )
 
     if not is_truthy(config.get("EnableOpenServer")):
         raise ValueError("EnableOpenServer not enabled")
@@ -16,6 +28,82 @@ Usage::
 
 from __future__ import annotations
 
+import requests
+
+
+class APIClient:
+    """Base class for HTTP API clients.
+
+    Subclasses set ``base_url``, ``headers``, and optionally ``auth`` in
+    their constructor, then use :meth:`_request` or the convenience
+    methods (:meth:`get`, :meth:`post`, etc.) to make requests.
+
+    All requests raise :class:`requests.HTTPError` on 4xx/5xx responses
+    via :meth:`requests.Response.raise_for_status`.
+    """
+
+    def __init__(
+        self,
+        base_url: str,
+        headers: dict,
+        timeout: int = 30,
+        verify: bool = True,
+        auth: tuple[str, str] | None = None,
+    ) -> None:
+        """Initialize the API client.
+
+        Args:
+            base_url: Base URL for the API (trailing slash stripped).
+            headers: Default headers sent with every request.
+            timeout: Request timeout in seconds.
+            verify: Whether to verify TLS certificates.
+            auth: Optional ``(username, password)`` tuple for basic auth.
+        """
+        self.base_url = base_url.rstrip("/")
+        self.headers = headers
+        self.timeout = timeout
+        self.verify = verify
+        self.auth = auth
+
+    def _request(self, method: str, path: str, **kwargs) -> requests.Response:
+        """Execute an HTTP request against the API.
+
+        The URL is constructed as ``{base_url}{path}``. Default timeout,
+        verify, auth, and headers are applied but can be overridden via
+        ``kwargs``.
+
+        Raises:
+            requests.HTTPError: On 4xx/5xx response status codes.
+        """
+        url = f"{self.base_url}{path}"
+        kwargs.setdefault("timeout", self.timeout)
+        kwargs.setdefault("verify", self.verify)
+        if self.auth is not None:
+            kwargs.setdefault("auth", self.auth)
+        resp = requests.request(method, url, headers=self.headers, **kwargs)  # noqa: S113
+        resp.raise_for_status()
+        return resp
+
+    def get(self, path: str, **kwargs) -> requests.Response:
+        """Send a GET request."""
+        return self._request("GET", path, **kwargs)
+
+    def post(self, path: str, **kwargs) -> requests.Response:
+        """Send a POST request."""
+        return self._request("POST", path, **kwargs)
+
+    def put(self, path: str, **kwargs) -> requests.Response:
+        """Send a PUT request."""
+        return self._request("PUT", path, **kwargs)
+
+    def delete(self, path: str, **kwargs) -> requests.Response:
+        """Send a DELETE request."""
+        return self._request("DELETE", path, **kwargs)
+
+    def patch(self, path: str, **kwargs) -> requests.Response:
+        """Send a PATCH request."""
+        return self._request("PATCH", path, **kwargs)
+
 
 def is_truthy(value: str | bool | None) -> bool:
     """Check if an API config value is truthy.

src/devx/utils/jinja.py

@@ -0,0 +1,133 @@
+"""Shared Jinja2 environment helpers for unit tests and template rendering.
+
+Creating a Jinja2 Environment is expensive (filesystem scanning, template
+compilation).  These helpers create cached environments with
+``auto_reload=False`` to skip stat() calls on every ``get_template``,
+which is the single biggest speedup for template-heavy test suites.
+
+The filters mimic Ansible builtins not available in plain Jinja2,
+making it possible to render Ansible templates outside of Ansible
+(e.g. in unit tests or config generation scripts).
+
+Usage::
+
+    from devx.utils.jinja import make_env, render_template
+
+    env = make_env("/path/to/templates")
+    output = render_template(env, "alert-rules.yml.j2", grafana_base_url="https://grafana.example.com")
+"""
+
+from __future__ import annotations
+
+import functools
+import json
+import re
+
+import jinja2
+
+# ---------------------------------------------------------------------------
+# Filters (mimic Ansible builtins not available in plain Jinja2)
+# ---------------------------------------------------------------------------
+
+
+def to_json(value) -> str:
+    return json.dumps(value)
+
+
+def to_bool(value) -> bool:
+    """Mimic Ansible's |bool filter for plain Jinja2 tests."""
+    if isinstance(value, bool):
+        return value
+    if isinstance(value, str):
+        return value.lower() not in ("", "false", "0", "no", "off", "null", "none")
+    return bool(value)
+
+
+def regex_replace(value, pattern: str, replacement: str) -> str:
+    """Mimic Ansible's |regex_replace filter."""
+    return re.sub(pattern, replacement, str(value))
+
+
+def regex_escape(value) -> str:
+    """Mimic Ansible's |regex_escape filter."""
+    return re.escape(str(value))
+
+
+def regex_search(value, pattern: str) -> str | None:
+    """Mimic Ansible's |regex_search filter.
+
+    Returns the first match (group 0) or None if no match.
+    Ansible returns the full match string or None.
+    """
+    m = re.search(pattern, str(value))
+    return m.group(0) if m else None
+
+
+# ---------------------------------------------------------------------------
+# Environment factory
+# ---------------------------------------------------------------------------
+
+_FILTERS = {
+    "to_json": to_json,
+    "bool": to_bool,
+    "regex_replace": regex_replace,
+    "regex_escape": regex_escape,
+    "regex_search": regex_search,
+}
+
+
+@functools.cache
+def make_env(loader_path: str) -> jinja2.Environment:
+    """Create a cached Jinja2 Environment with standard filters.
+
+    ``auto_reload=False`` skips stat() on every get_template call —
+    templates don't change during a test run so this is safe and
+    cuts ~40% off render time.
+    """
+    env = jinja2.Environment(  # nosec B701 — renders YAML/config templates, not HTML
+        loader=jinja2.FileSystemLoader(loader_path),
+        undefined=jinja2.StrictUndefined,
+        auto_reload=False,
+        cache_size=400,
+    )
+    env.filters.update(_FILTERS)
+    return env
+
+
+@functools.cache
+def make_value_env() -> jinja2.Environment:
+    """Cached environment for rendering individual manifest string values."""
+    env = jinja2.Environment(  # nosec B701 — renders config values, not HTML
+        undefined=jinja2.ChainableUndefined,
+        auto_reload=False,
+    )
+    env.filters.update(_FILTERS)
+    return env
+
+
+# ---------------------------------------------------------------------------
+# Render helpers
+# ---------------------------------------------------------------------------
+
+
+def render_template(env: jinja2.Environment, template_name: str, **kwargs) -> str:
+    """Render a named template from a FileSystemLoader-backed env."""
+    return env.get_template(template_name).render(**kwargs)
+
+
+def render_value(value, ctx: dict):
+    """Render a single string value as a Jinja2 template if it contains expressions."""
+    if not isinstance(value, str):
+        return value
+    if "{{" not in value and "{%" not in value:
+        return value
+    return make_value_env().from_string(value).render(**ctx)
+
+
+def render_manifest_values(obj, ctx: dict):
+    """Recursively render all Jinja2 expressions in manifest string values."""
+    if isinstance(obj, dict):
+        return {k: render_manifest_values(v, ctx) for k, v in obj.items()}
+    if isinstance(obj, list):
+        return [render_manifest_values(v, ctx) for v in obj]
+    return render_value(obj, ctx)

src/devx/utils/ui.py

@@ -0,0 +1,79 @@
+"""User-facing output utilities combining console and log output.
+
+Console messages are colorised via ``click.style`` for visual feedback.
+The persistent log file always receives plain text (no ANSI codes).
+
+This is a generalisation of grm's ``ui.say()`` function, extracted so
+that any CLI tool can use the same pattern.  The logger name and
+console-level env var are configurable.
+
+Usage::
+
+    from devx.utils.ui import say
+
+    say("Starting deployment...")
+    say("Error occurred", level=logging.ERROR, err=True, color="red")
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+
+import click
+
+# Configurable env var for console verbosity — projects can override
+# via :func:`configure_ui`.
+_LOG_LEVEL_ENV_VAR = "DEVX_LOG_LEVEL"
+_LOGGER_NAME = "devx"
+
+
+def configure_ui(*, log_level_env_var: str = "DEVX_LOG_LEVEL", logger_name: str = "devx") -> None:
+    """Override the env var name and logger name used by :func:`say`.
+
+    This allows downstream projects (e.g. grm) to use their own env var
+    names (e.g. ``GRM_LOG_LEVEL``) and logger names while still using
+    devx's ui module.
+
+    Args:
+        log_level_env_var: Environment variable name for console log level.
+        logger_name: Logger name for persistent log file output.
+    """
+    global _LOG_LEVEL_ENV_VAR, _LOGGER_NAME
+    _LOG_LEVEL_ENV_VAR = log_level_env_var
+    _LOGGER_NAME = logger_name
+
+
+def _console_level() -> int:
+    """Return the minimum level for console output from the configured env var."""
+    value = os.getenv(_LOG_LEVEL_ENV_VAR, "INFO")
+    try:
+        return getattr(logging, value.upper())
+    except AttributeError:
+        return logging.INFO
+
+
+def say(
+    msg: str,
+    level: int = logging.INFO,
+    err: bool = False,
+    color: str | None = None,
+) -> None:
+    """Output a message to the user and also log it for auditing.
+
+    Console output goes via ``click.echo`` (handles encoding, CliRunner,
+    Windows colorama) only when *level* is at least the configured
+    console log level (default ``DEVX_LOG_LEVEL``, falls back to INFO).
+    The same message is always sent to the configured logger so it
+    appears in the persistent log file regardless of console verbosity.
+
+    Args:
+        msg: Message to display.
+        level: Logging level (e.g. ``logging.INFO``, ``logging.ERROR``).
+        err: If True, output to stderr instead of stdout.
+        color: Optional ``click.style`` fg color (e.g. ``"green"``, ``"red"``).
+    """
+    if level >= _console_level():
+        styled = click.style(msg, fg=color) if color else msg
+        click.echo(styled, err=err)
+    logging.getLogger(_LOGGER_NAME).log(level, msg)

tests/unit/test_api_clients.py

@@ -316,6 +316,18 @@ class TestGiteaClient:
         call_kwargs = client._session.request.call_args.kwargs
         assert call_kwargs["json"]["base"] == "develop"
 
+    def test_update_pr(self) -> None:
+        client = GiteaClient("https://git.example.com", "tok", "owner", "repo")
+        client._session.request = MagicMock(return_value=_mock_response({"number": 42, "title": "DEVX-99: New title"}))
+        result = client.update_pr(42, {"title": "DEVX-99: New title"})
+        assert result["number"] == 42
+        client._session.request.assert_called_once_with(
+            "PATCH",
+            "https://git.example.com/repos/owner/repo/pulls/42",
+            timeout=DEFAULT_TIMEOUT,
+            json={"title": "DEVX-99: New title"},
+        )
+
     def test_get_pr_files(self) -> None:
         client = GiteaClient("https://git.example.com", "tok", "owner", "repo")
         client._session.request = MagicMock(

tests/unit/test_build_image.py

@@ -13,7 +13,9 @@ from click.testing import CliRunner
 import devx.tools.build_image as build_image
 from devx.tools.build_image import (
     ImageSpec,
+    PushHTTP500Error,
     build_full_tag,
+    delete_remote_manifest,
     load_manifest,
     push_image,
     registry_login,
@@ -196,7 +198,7 @@ class TestBuildImage:
 class TestPushImage:
     def test_success(self) -> None:
         spec = ImageSpec(name="ci-base", dockerfile="Dockerfile", tags=["latest", "1.0"])
-        mock_result = MagicMock(returncode=0, stderr="", stdout="")
+        mock_result = MagicMock(returncode=0, stdout="")
         with patch("devx.tools.build_image.subprocess.run", return_value=mock_result) as mock_run:
             assert push_image(spec, "git.example.com") is True
             assert mock_run.call_count == 2
@@ -204,8 +206,8 @@ class TestPushImage:
     def test_partial_failure(self) -> None:
         spec = ImageSpec(name="ci-base", dockerfile="Dockerfile", tags=["latest", "1.0"])
         results = [
-            MagicMock(returncode=0, stderr="", stdout=""),
-            MagicMock(returncode=1, stderr="push failed", stdout=""),
+            MagicMock(returncode=0, stdout=""),
+            MagicMock(returncode=1, stdout="push failed"),
         ]
         with patch("devx.tools.build_image.subprocess.run", side_effect=results):
             assert push_image(spec, "git.example.com") is False
@@ -216,6 +218,212 @@ class TestPushImage:
             assert push_image(spec, "git.example.com", dry_run=True) is True
             mock_run.assert_not_called()
 
+    def test_no_delete_on_success_with_creds(self) -> None:
+        """Push-first: no delete needed when push succeeds."""
+        spec = ImageSpec(name="ci-base", dockerfile="Dockerfile", tags=["latest"])
+        mock_result = MagicMock(returncode=0, stdout="")
+        with (
+            patch("devx.tools.build_image.subprocess.run", return_value=mock_result),
+            patch("devx.tools.build_image.delete_remote_manifest") as mock_del,
+        ):
+            assert push_image(spec, "git.example.com", username="user", token="tok") is True
+            mock_del.assert_not_called()
+
+    def test_no_delete_without_creds(self) -> None:
+        spec = ImageSpec(name="ci-base", dockerfile="Dockerfile", tags=["latest"])
+        mock_result = MagicMock(returncode=0, stdout="")
+        with (
+            patch("devx.tools.build_image.subprocess.run", return_value=mock_result),
+            patch("devx.tools.build_image.delete_remote_manifest") as mock_del,
+        ):
+            assert push_image(spec, "git.example.com") is True
+            mock_del.assert_not_called()
+
+    def test_delete_and_retry_on_already_exists(self) -> None:
+        """Gitea #31964: push fails with 'already exists', delete + retry."""
+        spec = ImageSpec(name="ci-base", dockerfile="Dockerfile", tags=["latest"])
+        results = [
+            MagicMock(returncode=1, stdout="package version already exists"),
+            MagicMock(returncode=0, stdout=""),
+        ]
+        with (
+            patch("devx.tools.build_image.subprocess.run", side_effect=results),
+            patch("devx.tools.build_image.delete_remote_manifest", return_value=True) as mock_del,
+        ):
+            assert push_image(spec, "git.example.com", username="user", token="tok") is True
+            mock_del.assert_called_once_with(
+                "git.example.com",
+                "ci-base",
+                "latest",
+                "user",
+                "tok",
+                dry_run=False,
+            )
+
+    def test_no_delete_on_non_already_exists_failure(self) -> None:
+        """Push fails for other reasons (non-500) — old manifest preserved."""
+        spec = ImageSpec(name="ci-base", dockerfile="Dockerfile", tags=["latest"])
+        mock_result = MagicMock(returncode=1, stdout="denied: requested access to the resource is denied")
+        with (
+            patch("devx.tools.build_image.subprocess.run", return_value=mock_result),
+            patch("devx.tools.build_image.delete_remote_manifest") as mock_del,
+        ):
+            assert push_image(spec, "git.example.com", username="user", token="tok") is False
+            mock_del.assert_not_called()
+
+    def test_retry_also_fails(self) -> None:
+        """Gitea #31964 retry also fails — both pushes fail."""
+        spec = ImageSpec(name="ci-base", dockerfile="Dockerfile", tags=["latest"])
+        results = [
+            MagicMock(returncode=1, stdout="package version already exists"),
+            MagicMock(returncode=1, stdout="push failed again"),
+        ]
+        with (
+            patch("devx.tools.build_image.subprocess.run", side_effect=results),
+            patch("devx.tools.build_image.delete_remote_manifest", return_value=True),
+        ):
+            assert push_image(spec, "git.example.com", username="user", token="tok") is False
+
+    def test_http_500_retries_then_succeeds(self) -> None:
+        """HTTP 500 from registry race condition — retry succeeds."""
+        spec = ImageSpec(name="ci-base", dockerfile="Dockerfile", tags=["latest"])
+        results = [
+            MagicMock(returncode=1, stdout="received unexpected HTTP status: 500 Internal Server Error"),
+            MagicMock(returncode=0, stdout=""),
+        ]
+        with (
+            patch("devx.tools.build_image.subprocess.run", side_effect=results),
+            patch("devx.tools.build_image.delete_remote_manifest") as mock_del,
+            patch("time.sleep"),
+        ):
+            assert push_image(spec, "git.example.com", username="user", token="tok") is True
+            mock_del.assert_not_called()
+
+    def test_http_500_retries_all_fail(self) -> None:
+        """HTTP 500 retries exhausted — push fails, no delete attempted."""
+        spec = ImageSpec(name="ci-base", dockerfile="Dockerfile", tags=["latest"])
+        mock_result = MagicMock(returncode=1, stdout="received unexpected HTTP status: 500 Internal Server Error")
+        with (
+            patch("devx.tools.build_image.subprocess.run", return_value=mock_result),
+            patch("devx.tools.build_image.delete_remote_manifest") as mock_del,
+            patch("time.sleep"),
+        ):
+            assert push_image(spec, "git.example.com", username="user", token="tok") is False
+            mock_del.assert_not_called()
+
+    def test_run_push_raises_on_500(self) -> None:
+        """_run_push raises PushHTTP500Error when stdout contains 500."""
+        from devx.tools.build_image import _run_push
+
+        mock_result = MagicMock(returncode=1, stdout="received unexpected HTTP status: 500 Internal Server Error")
+        with patch("devx.tools.build_image.subprocess.run", return_value=mock_result):
+            with pytest.raises(PushHTTP500Error, match="500"):
+                _run_push(["docker", "push", "img:latest"])
+
+    def test_run_push_no_raise_on_non_500(self) -> None:
+        """_run_push returns result when stdout has no 500."""
+        from devx.tools.build_image import _run_push
+
+        mock_result = MagicMock(returncode=1, stdout="denied: access denied")
+        with patch("devx.tools.build_image.subprocess.run", return_value=mock_result):
+            result = _run_push(["docker", "push", "img:latest"])
+            assert result.returncode == 1
+
+    def test_run_push_no_raise_on_success(self) -> None:
+        """_run_push returns result on success."""
+        from devx.tools.build_image import _run_push
+
+        mock_result = MagicMock(returncode=0, stdout="")
+        with patch("devx.tools.build_image.subprocess.run", return_value=mock_result):
+            result = _run_push(["docker", "push", "img:latest"])
+            assert result.returncode == 0
+
+
+class TestDeleteRemoteManifest:
+    def test_dry_run(self) -> None:
+        assert delete_remote_manifest("git.example.com", "ci-base", "latest", "u", "t", dry_run=True) is True
+
+    def test_tag_not_found(self) -> None:
+        import urllib.error
+
+        with patch("devx.tools.build_image.urllib.request.urlopen") as mock_urlopen:
+            mock_urlopen.side_effect = urllib.error.HTTPError("url", 404, "Not Found", {}, None)
+            assert delete_remote_manifest("git.example.com", "ci-base", "latest", "u", "t") is True
+
+    def test_delete_success(self) -> None:
+        mock_head_resp = MagicMock()
+        mock_head_resp.__enter__.return_value.headers.get.return_value = "sha256:abc123"
+        mock_del_resp = MagicMock()
+        with patch("devx.tools.build_image.urllib.request.urlopen") as mock_urlopen:
+            mock_urlopen.side_effect = [mock_head_resp, mock_del_resp]
+            assert delete_remote_manifest("git.example.com", "ci-base", "latest", "u", "t") is True
+
+    def test_delete_404_treated_as_success(self) -> None:
+        import urllib.error
+
+        mock_head_resp = MagicMock()
+        mock_head_resp.__enter__.return_value.headers.get.return_value = "sha256:abc123"
+        with patch("devx.tools.build_image.urllib.request.urlopen") as mock_urlopen:
+            mock_urlopen.side_effect = [
+                mock_head_resp,
+                urllib.error.HTTPError("url", 404, "Not Found", {}, None),
+            ]
+            assert delete_remote_manifest("git.example.com", "ci-base", "latest", "u", "t") is True
+
+    def test_head_error_does_not_block(self) -> None:
+        import urllib.error
+
+        with patch("devx.tools.build_image.urllib.request.urlopen") as mock_urlopen:
+            mock_urlopen.side_effect = urllib.error.HTTPError("url", 500, "Server Error", {}, None)
+            assert delete_remote_manifest("git.example.com", "ci-base", "latest", "u", "t") is True
+
+    def test_url_error_does_not_block(self) -> None:
+        import urllib.error
+
+        with patch("devx.tools.build_image.urllib.request.urlopen") as mock_urlopen:
+            mock_urlopen.side_effect = urllib.error.URLError("network down")
+            assert delete_remote_manifest("git.example.com", "ci-base", "latest", "u", "t") is True
+
+    def test_no_digest_does_not_block(self) -> None:
+        mock_head_resp = MagicMock()
+        mock_head_resp.__enter__.return_value.headers.get.return_value = None
+        with patch("devx.tools.build_image.urllib.request.urlopen") as mock_urlopen:
+            mock_urlopen.return_value = mock_head_resp
+            assert delete_remote_manifest("git.example.com", "ci-base", "latest", "u", "t") is True
+
+    def test_head_405_passes_through(self) -> None:
+        import urllib.error
+
+        with patch("devx.tools.build_image.urllib.request.urlopen") as mock_urlopen:
+            mock_urlopen.side_effect = urllib.error.HTTPError("url", 405, "Method Not Allowed", {}, None)
+            # 405 falls through with pass, digest never set, returns True
+            assert delete_remote_manifest("git.example.com", "ci-base", "latest", "u", "t") is True
+            assert mock_urlopen.call_count == 1
+
+    def test_delete_500_does_not_block(self) -> None:
+        import urllib.error
+
+        mock_head_resp = MagicMock()
+        mock_head_resp.__enter__.return_value.headers.get.return_value = "sha256:abc123"
+        with patch("devx.tools.build_image.urllib.request.urlopen") as mock_urlopen:
+            mock_urlopen.side_effect = [
+                mock_head_resp,
+                urllib.error.HTTPError("url", 500, "Server Error", {}, None),
+            ]
+            assert delete_remote_manifest("git.example.com", "ci-base", "latest", "u", "t") is True
+
+    def test_delete_url_error_does_not_block(self) -> None:
+        import urllib.error
+
+        mock_head_resp = MagicMock()
+        mock_head_resp.__enter__.return_value.headers.get.return_value = "sha256:abc123"
+        with patch("devx.tools.build_image.urllib.request.urlopen") as mock_urlopen:
+            mock_urlopen.side_effect = [
+                mock_head_resp,
+                urllib.error.URLError("network down"),
+            ]
+            assert delete_remote_manifest("git.example.com", "ci-base", "latest", "u", "t") is True
+
 
 class TestSortVersions:
     def test_sort_by_created_at_desc(self) -> None:
@@ -508,7 +716,8 @@ class TestCLIBuildImage:
 
     def test_missing_dockerfile_and_manifest(self) -> None:
         runner = CliRunner()
-        result = runner.invoke(build_image.main, [])
+        with patch("devx.tools.build_image.subprocess.run"):
+            result = runner.invoke(build_image.main, [])
         assert result.exit_code != 0
         assert "manifest" in result.output.lower() or "dockerfile" in result.output.lower()
 
@@ -516,10 +725,11 @@ class TestCLIBuildImage:
         dockerfile = tmp_path / "Dockerfile"
         dockerfile.touch()
         runner = CliRunner()
-        result = runner.invoke(
-            build_image.main,
-            ["--dockerfile", str(dockerfile), "--name", "ci-base", "--push"],
-        )
+        with patch("devx.tools.build_image.subprocess.run"):
+            result = runner.invoke(
+                build_image.main,
+                ["--dockerfile", str(dockerfile), "--name", "ci-base", "--push"],
+            )
         assert result.exit_code != 0
         assert "registry" in result.output.lower()
 
@@ -527,7 +737,7 @@ class TestCLIBuildImage:
         dockerfile = tmp_path / "Dockerfile"
         dockerfile.touch()
         runner = CliRunner()
-        with patch.dict("os.environ", {}, clear=True):
+        with patch("devx.tools.build_image.subprocess.run"), patch.dict("os.environ", {}, clear=True):
             result = runner.invoke(
                 build_image.main,
                 ["--dockerfile", str(dockerfile), "--name", "ci-base", "--push", "--registry", "git.example.com"],
@@ -586,11 +796,20 @@ class TestCLIBuildImage:
                 "devx.tools.build_image.subprocess.run",
                 side_effect=[login_result, build_result, push_result],
             ):
-                result = runner.invoke(
-                    build_image.main,
-                    ["--dockerfile", str(dockerfile), "--name", "ci-base", "--push", "--registry", "git.example.com"],
-                )
-                assert result.exit_code != 0
+                with patch("devx.tools.build_image.delete_remote_manifest", return_value=True):
+                    result = runner.invoke(
+                        build_image.main,
+                        [
+                            "--dockerfile",
+                            str(dockerfile),
+                            "--name",
+                            "ci-base",
+                            "--push",
+                            "--registry",
+                            "git.example.com",
+                        ],
+                    )
+                    assert result.exit_code != 0
 
 
 class TestCLICleanImages:

tests/unit/test_check_auto_merge_ready.py

@@ -152,7 +152,10 @@ class TestGetVikunjaTitleOptional:
 class TestCli:
     def test_fails_without_task_id(self) -> None:
         runner = CliRunner()
-        with patch.dict("os.environ", {"DEVX_TASK_PREFIX": "DEVX"}, clear=True):
+        with (
+            patch.dict("os.environ", {"DEVX_TASK_PREFIX": "DEVX"}, clear=True),
+            patch("devx.ci.check_auto_merge_ready.is_branch_behind_master", return_value=False),
+        ):
             result = runner.invoke(cli, ["--branch", "no-task-id-here"])
         assert result.exit_code != 0
 
@@ -242,6 +245,7 @@ class TestCli:
         runner = CliRunner()
         with (
             patch.dict("os.environ", {"DEVX_TASK_PREFIX": "DEVX", "VIKUNJA_TOKEN": ""}, clear=True),
+            patch("devx.ci.check_auto_merge_ready.is_branch_behind_master", return_value=False),
             patch("devx.ci.check_auto_merge_ready.get_pr_title_from_gitea", return_value=None),
         ):
             result = runner.invoke(

tests/unit/test_check_pr_size.py

@@ -0,0 +1,169 @@
+"""Unit tests for devx.ci.check_pr_size."""
+
+from unittest.mock import MagicMock, patch
+
+from click.testing import CliRunner
+
+from devx.ci.check_pr_size import (
+    check_size,
+    cli,
+    get_diff_stats,
+    has_refactoring_label,
+    is_excluded,
+)
+
+
+class TestIsExcluded:
+    def test_excludes_changelog(self) -> None:
+        assert is_excluded("CHANGELOG.md", ["CHANGELOG.md"])
+
+    def test_excludes_svg_glob(self) -> None:
+        assert is_excluded("docs/badges/coverage.svg", ["*.svg"])
+
+    def test_does_not_exclude_source(self) -> None:
+        assert not is_excluded("src/devx/ci/check_pr_size.py", ["CHANGELOG.md", "*.svg"])
+
+    def test_excludes_readme(self) -> None:
+        assert is_excluded("README.md", ["README.md"])
+
+
+class TestCheckSize:
+    def test_under_limits_passes(self) -> None:
+        stats = [("src/main.py", 100, 50), ("tests/test_main.py", 80, 20)]
+        ok, detail = check_size(stats, max_lines=500, max_files=10, excluded_patterns=[])
+        assert ok is True
+        assert "250" in detail  # 100+50+80+20
+
+    def test_over_lines_fails(self) -> None:
+        stats = [("src/main.py", 300, 300)]
+        ok, detail = check_size(stats, max_lines=500, max_files=10, excluded_patterns=[])
+        assert ok is False
+        assert "600" in detail
+
+    def test_over_files_fails(self) -> None:
+        stats = [(f"src/file{i}.py", 10, 5) for i in range(15)]
+        ok, detail = check_size(stats, max_lines=500, max_files=10, excluded_patterns=[])
+        assert ok is False
+        assert "15" in detail
+
+    def test_excluded_files_not_counted(self) -> None:
+        stats = [("CHANGELOG.md", 500, 500), ("src/main.py", 10, 5)]
+        ok, detail = check_size(stats, max_lines=500, max_files=10, excluded_patterns=["CHANGELOG.md"])
+        assert ok is True
+        assert "15" in detail  # only 10+5
+
+    def test_empty_stats_passes(self) -> None:
+        ok, detail = check_size([], max_lines=500, max_files=10, excluded_patterns=[])
+        assert ok is True
+
+
+class TestGetDiffStats:
+    @patch("devx.ci.check_pr_size.subprocess.run")
+    def test_parses_numstat_output(self, mock_run: MagicMock) -> None:
+        mock_run.return_value = MagicMock(
+            returncode=0,
+            stdout="10\t5\tsrc/main.py\n20\t10\ttests/test_main.py\n",
+            stderr="",
+        )
+        stats = get_diff_stats("origin/master", "HEAD")
+        assert len(stats) == 2
+        assert stats[0] == ("src/main.py", 10, 5)
+        assert stats[1] == ("tests/test_main.py", 20, 10)
+
+    @patch("devx.ci.check_pr_size.subprocess.run")
+    def test_handles_binary_files(self, mock_run: MagicMock) -> None:
+        mock_run.return_value = MagicMock(
+            returncode=0,
+            stdout="-\t-\timage.png\n",
+            stderr="",
+        )
+        stats = get_diff_stats("origin/master", "HEAD")
+        assert len(stats) == 1
+        assert stats[0] == ("image.png", 0, 0)
+
+    @patch("devx.ci.check_pr_size.subprocess.run")
+    def test_empty_output(self, mock_run: MagicMock) -> None:
+        mock_run.return_value = MagicMock(returncode=0, stdout="", stderr="")
+        stats = get_diff_stats("origin/master", "HEAD")
+        assert stats == []
+
+    @patch("devx.ci.check_pr_size.subprocess.run")
+    def test_git_diff_failure_raises(self, mock_run: MagicMock) -> None:
+        import pytest
+
+        mock_run.return_value = MagicMock(returncode=1, stdout="", stderr="fatal: bad ref")
+        with pytest.raises(Exception, match="git diff|bad ref"):
+            get_diff_stats("origin/master", "HEAD")
+
+    @patch("devx.ci.check_pr_size.subprocess.run")
+    def test_malformed_line_skipped(self, mock_run: MagicMock) -> None:
+        mock_run.return_value = MagicMock(
+            returncode=0,
+            stdout="not_a_valid_line\n10\t5\tsrc/main.py\n",
+            stderr="",
+        )
+        stats = get_diff_stats("origin/master", "HEAD")
+        assert len(stats) == 1
+        assert stats[0] == ("src/main.py", 10, 5)
+
+
+class TestCli:
+    @patch("devx.ci.check_pr_size.subprocess.run")
+    def test_passes_when_small(self, mock_run: MagicMock) -> None:
+        mock_run.return_value = MagicMock(
+            returncode=0,
+            stdout="10\t5\tsrc/main.py\n",
+            stderr="",
+        )
+        runner = CliRunner()
+        result = runner.invoke(cli, ["--base", "origin/master", "--head", "HEAD"])
+        assert result.exit_code == 0
+        assert "OK" in result.output
+
+    @patch("devx.ci.check_pr_size.subprocess.run")
+    def test_fails_when_too_large(self, mock_run: MagicMock) -> None:
+        mock_run.return_value = MagicMock(
+            returncode=0,
+            stdout="300\t300\tsrc/main.py\n",
+            stderr="",
+        )
+        runner = CliRunner()
+        result = runner.invoke(cli, ["--base", "origin/master", "--head", "HEAD", "--max-lines", "500"])
+        assert result.exit_code != 0
+        assert "600" in result.output
+
+    @patch("devx.ci.check_pr_size.subprocess.run")
+    @patch("devx.ci.check_pr_size.has_refactoring_label", return_value=True)
+    def test_bypasses_with_refactoring_label(self, mock_label: MagicMock, mock_run: MagicMock) -> None:
+        mock_run.return_value = MagicMock(
+            returncode=0,
+            stdout="300\t300\tsrc/main.py\n",
+            stderr="",
+        )
+        runner = CliRunner()
+        result = runner.invoke(
+            cli,
+            ["--base", "origin/master", "--head", "HEAD", "--repo", "owner/repo", "--pr-number", "42"],
+        )
+        assert result.exit_code == 0
+        assert "bypassed" in result.output.lower()
+
+
+class TestHasRefactoringLabel:
+    @patch("devx.ci.check_pr_size.GiteaClient")
+    @patch("devx.ci.check_pr_size.get_ci_token", return_value="fake-token")
+    def test_returns_true_when_label_present(self, mock_token: MagicMock, mock_client_cls: MagicMock) -> None:
+        mock_client = mock_client_cls.return_value
+        mock_client.get_pr.return_value = {"labels": [{"name": "refactoring"}, {"name": "bug"}]}
+        assert has_refactoring_label("owner/repo", 42) is True
+
+    @patch("devx.ci.check_pr_size.GiteaClient")
+    @patch("devx.ci.check_pr_size.get_ci_token", return_value="fake-token")
+    def test_returns_false_when_label_absent(self, mock_token: MagicMock, mock_client_cls: MagicMock) -> None:
+        mock_client = mock_client_cls.return_value
+        mock_client.get_pr.return_value = {"labels": [{"name": "bug"}]}
+        assert has_refactoring_label("owner/repo", 42) is False
+
+    @patch("devx.ci.check_pr_size.get_ci_token", side_effect=Exception("no token"))
+    def test_returns_false_on_error(self, mock_token: MagicMock) -> None:
+        assert has_refactoring_label("owner/repo", 42) is False

tests/unit/test_check_test_isolation.py

@@ -2,14 +2,26 @@
 
 from __future__ import annotations
 
+import ast
+import subprocess
 import textwrap
 from pathlib import Path
+from unittest.mock import MagicMock
 
+import pytest
 from click.testing import CliRunner
 
 from devx.tools.check_test_isolation import (
+    HEAVY_MODULE_IMPORTS,
     HELPER_INTERNAL_CALLS,
+    IO_INTERNAL_CALLS,
+    KNOWN_IO_FUNCTIONS,
     KNOWN_SUBPROCESS_HELPERS,
+    CallGraph,
+    _extract_patch_targets,
+    _is_integration_test,
+    _load_test_isolation_config,
+    _SubprocessAudit,
     analyze_file,
     analyze_test_files,
     cli,
@@ -502,6 +514,97 @@ class TestAnalyzeFile:
         assert len(violations) == 1
         assert violations[0].category == "syntax-error"
 
+    def test_heavy_module_import_at_module_level(self, tmp_path: Path) -> None:
+        file = _write_test_file(
+            tmp_path,
+            """
+            import pandas
+
+            def test_foo() -> None:
+                assert True
+        """,
+        )
+        violations = analyze_file(file)
+        assert len(violations) == 1
+        assert violations[0].category == "heavy-module-import"
+        assert "pandas" in violations[0].message
+
+    def test_heavy_import_inside_function_ok(self, tmp_path: Path) -> None:
+        file = _write_test_file(
+            tmp_path,
+            """
+            def test_foo() -> None:
+                import pandas
+                assert True
+        """,
+        )
+        violations = analyze_file(file)
+        assert violations == []
+
+    def test_heavy_import_from_at_module_level(self, tmp_path: Path) -> None:
+        file = _write_test_file(
+            tmp_path,
+            """
+            from matplotlib import pyplot as plt
+
+            def test_foo() -> None:
+                assert True
+        """,
+        )
+        violations = analyze_file(file)
+        assert len(violations) == 1
+        assert violations[0].category == "heavy-module-import"
+
+    def test_reload_without_cleanup_odd_count(self, tmp_path: Path) -> None:
+        file = _write_test_file(
+            tmp_path,
+            """
+            import importlib
+            import devx.config as cfg
+
+            def test_reload_no_cleanup() -> None:
+                importlib.reload(cfg)
+                assert cfg.TASK_PREFIX == "CUSTOM"
+        """,
+        )
+        violations = analyze_file(file)
+        reload_violations = [v for v in violations if v.category == "reload-without-cleanup"]
+        assert len(reload_violations) == 1
+        assert "1 time(s)" in reload_violations[0].message
+
+    def test_reload_with_cleanup_even_count_ok(self, tmp_path: Path) -> None:
+        file = _write_test_file(
+            tmp_path,
+            """
+            import importlib
+            import devx.config as cfg
+
+            def test_reload_with_cleanup() -> None:
+                importlib.reload(cfg)
+                assert cfg.TASK_PREFIX == "CUSTOM"
+                importlib.reload(cfg)
+        """,
+        )
+        violations = analyze_file(file)
+        reload_violations = [v for v in violations if v.category == "reload-without-cleanup"]
+        assert reload_violations == []
+
+    def test_reload_attribute_access_detected(self, tmp_path: Path) -> None:
+        file = _write_test_file(
+            tmp_path,
+            """
+            import importlib
+            import devx.config
+
+            def test_reload_attr() -> None:
+                importlib.reload(devx.config)
+        """,
+        )
+        violations = analyze_file(file)
+        reload_violations = [v for v in violations if v.category == "reload-without-cleanup"]
+        assert len(reload_violations) == 1
+        assert "config" in reload_violations[0].message
+
 
 class TestAnalyzeTestFiles:
     def test_multiple_files(self, tmp_path: Path) -> None:
@@ -742,7 +845,8 @@ class TestCli:
         assert "FAILED" in result.output
         assert "unpatched-subprocess" in result.output
 
-    def test_strict_flag(self, tmp_path: Path) -> None:
+    def test_always_strict(self, tmp_path: Path) -> None:
+        """CLI is always strict — no --strict flag needed."""
         _write_test_file(
             tmp_path,
             """
@@ -753,7 +857,7 @@ class TestCli:
         """,
         )
         runner = CliRunner()
-        result = runner.invoke(cli, ["--test-path", str(tmp_path), "--strict"])
+        result = runner.invoke(cli, ["--test-path", str(tmp_path)])
         assert result.exit_code == 1
 
     def test_category_filter(self, tmp_path: Path) -> None:
@@ -795,22 +899,6 @@ class TestCli:
         assert result.exit_code == 0
         assert "no violations" in result.output
 
-    def test_strict_clean_directory_exits_zero(self, tmp_path: Path) -> None:
-        """Strict mode with no violations should still exit 0."""
-        _write_test_file(
-            tmp_path,
-            """
-            from unittest.mock import patch, MagicMock
-            class TestExample:
-                @patch("subprocess.run")
-                def test_ok(self, mock: MagicMock) -> None:
-                    pass
-        """,
-        )
-        runner = CliRunner()
-        result = runner.invoke(cli, ["--test-path", str(tmp_path), "--strict"])
-        assert result.exit_code == 0
-
 
 class TestPytestPlugin:
     """Tests for the pytest plugin hooks.
@@ -830,7 +918,7 @@ class TestPytestPlugin:
         pytest_addoption(parser)
 
         addoption_calls = parser.addoption.call_args_list
-        assert len(addoption_calls) >= 3
+        assert len(addoption_calls) >= 2
 
     def test_pytest_collection_finish_noop_when_disabled(self) -> None:
         """Plugin should skip analysis when --no-test-isolation is set."""
@@ -854,39 +942,10 @@ class TestPytestPlugin:
         pytest_collection_finish(session)
 
     def test_pytest_collection_finish_with_violation(self, tmp_path: Path) -> None:
-        """Plugin should emit warnings when violations are found."""
-        import warnings
+        """Plugin should fail when hard violations are found (always strict)."""
         from unittest.mock import MagicMock
 
-        from devx.tools.check_test_isolation import pytest_collection_finish
-
-        test_file = _write_test_file(
-            tmp_path,
-            """
-            import subprocess
-            class TestExample:
-                def test_bad(self) -> None:
-                    subprocess.run(["echo"])
-        """,
-        )
-
-        session = MagicMock()
-        session.config.getoption.side_effect = lambda opt: False
-        item = MagicMock()
-        item.fspath = str(test_file)
-        session.items = [item]
-
-        with warnings.catch_warnings(record=True) as w:
-            warnings.simplefilter("always")
-            pytest_collection_finish(session)
-
-        assert len(w) >= 1
-        assert any("Test isolation violation" in str(warning.message) for warning in w)
-
-    def test_pytest_collection_finish_strict_mode(self, tmp_path: Path) -> None:
-        """Plugin should emit warnings and print summary in strict mode."""
-        import warnings
-        from unittest.mock import MagicMock
+        import pytest
 
         from devx.tools.check_test_isolation import pytest_collection_finish
 
@@ -903,7 +962,44 @@ class TestPytestPlugin:
         session = MagicMock()
         session.config.getoption.side_effect = lambda opt: {
             "--no-test-isolation": False,
-            "--strict-test-isolation": True,
+            "--test-isolation-max-loop": 100,
+        }.get(opt, False)
+        item = MagicMock()
+        item.fspath = str(test_file)
+        session.items = [item]
+
+        with pytest.raises(pytest.fail.Exception, match="Test isolation"):
+            pytest_collection_finish(session)
+
+    def test_pytest_collection_finish_advisory_only(self, tmp_path: Path) -> None:
+        """Transitive-subprocess advisories should warn, not fail."""
+        import warnings
+        from unittest.mock import MagicMock
+
+        from devx.tools.check_test_isolation import pytest_collection_finish
+
+        # Create a src/ directory with a module that calls subprocess.run
+        # so the call graph can detect transitive subprocess calls.
+        src_dir = tmp_path / "src" / "mypkg"
+        src_dir.mkdir(parents=True)
+        (src_dir / "__init__.py").write_text("")
+        (src_dir / "cli.py").write_text("import subprocess\ndef main():\n    subprocess.run(['echo'])\n")
+
+        test_file = _write_test_file(
+            tmp_path,
+            """
+            from click.testing import CliRunner
+            from mypkg.cli import main
+            class TestExample:
+                def test_advisory(self) -> None:
+                    runner = CliRunner()
+                    result = runner.invoke(main, [])
+        """,
+        )
+
+        session = MagicMock()
+        session.config.getoption.side_effect = lambda opt: {
+            "--no-test-isolation": False,
             "--test-isolation-max-loop": 100,
         }.get(opt, False)
         item = MagicMock()
@@ -914,5 +1010,772 @@ class TestPytestPlugin:
             warnings.simplefilter("always")
             pytest_collection_finish(session)
 
-        assert len(w) >= 1
-        assert any("Test isolation violation" in str(warning.message) for warning in w)
+        # Should only emit advisory warnings, not fail
+        assert any("advisory" in str(warning.message).lower() for warning in w)
+
+
+class TestSubprocessAudit:
+    """Tests for the _SubprocessAudit runtime wrapper (lines 157-195)."""
+
+    def test_ensure_installed_wraps_subprocess(self) -> None:
+        audit = _SubprocessAudit()
+        original_run = subprocess.run
+        try:
+            audit._ensure_installed()
+            assert audit._installed is True
+            assert "run" in audit._originals
+            # The subprocess.run should now be a wrapper, not the original
+            assert subprocess.run is not original_run
+            # Calling _ensure_installed again is a no-op (cached return)
+            audit._ensure_installed()
+        finally:
+            # Restore originals
+            for name, orig in audit._originals.items():
+                setattr(subprocess, name, orig)
+
+    def test_make_wrapper_records_calls_when_active(self) -> None:
+        audit = _SubprocessAudit()
+        mock_original = MagicMock(return_value="result")
+        wrapper = audit._make_wrapper("run", mock_original)
+        audit.start_test()
+        result = wrapper(["echo", "hi"], capture_output=True)
+        calls = audit.stop_test()
+        assert result == "result"
+        run_calls = [c for c in calls if c[0] == "run"]
+        assert len(run_calls) == 1
+        assert "echo" in run_calls[0][1]
+        mock_original.assert_called_once_with(["echo", "hi"], capture_output=True)
+
+    def test_make_wrapper_records_list_cmd_truncation(self) -> None:
+        """Long command lists should be truncated to first 4 elements."""
+        audit = _SubprocessAudit()
+        mock_original = MagicMock(return_value="result")
+        wrapper = audit._make_wrapper("run", mock_original)
+        audit.start_test()
+        wrapper(["echo", "1", "2", "3", "4", "5", "6"], capture_output=True)
+        calls = audit.stop_test()
+        run_calls = [c for c in calls if c[0] == "run"]
+        assert len(run_calls) == 1
+        assert "..." in run_calls[0][1]
+
+    def test_make_wrapper_records_string_cmd(self) -> None:
+        """A string command (not list) should be recorded as-is."""
+        audit = _SubprocessAudit()
+        mock_original = MagicMock(return_value="result")
+        wrapper = audit._make_wrapper("run", mock_original)
+        audit.start_test()
+        wrapper("echo hi", shell=True, capture_output=True)
+        calls = audit.stop_test()
+        run_calls = [c for c in calls if c[0] == "run"]
+        assert len(run_calls) == 1
+        assert "echo hi" in run_calls[0][1]
+
+    def test_calls_not_recorded_when_inactive(self) -> None:
+        """When audit is not active, calls should not be recorded."""
+        audit = _SubprocessAudit()
+        mock_original = MagicMock(return_value="result")
+        wrapper = audit._make_wrapper("run", mock_original)
+        # Don't call start_test — audit inactive
+        wrapper(["echo", "hi"], capture_output=True)
+        # stop_test returns empty since no calls recorded
+        calls = audit.stop_test()
+        assert not calls
+        mock_original.assert_called_once_with(["echo", "hi"], capture_output=True)
+
+    def test_start_then_stop_returns_calls(self) -> None:
+        """start_test initializes calls list, stop_test returns and clears it."""
+        audit = _SubprocessAudit()
+        mock_original = MagicMock(return_value="result")
+        wrapper = audit._make_wrapper("run", mock_original)
+        audit.start_test()
+        wrapper(["echo"], capture_output=True)
+        calls = audit.stop_test()
+        assert len(calls) == 1
+        # After stop, calls is cleared (None or empty)
+        calls2 = audit.stop_test()
+        assert not calls2
+
+    def test_ensure_installed_skips_missing_funcs(self) -> None:
+        """If a subprocess func is missing (None), it should be skipped (line 162)."""
+        audit = _SubprocessAudit()
+        saved = subprocess.check_output
+        try:
+            # Temporarily make check_output "missing" (None)
+            subprocess.check_output = None  # type: ignore[assignment]
+            audit._ensure_installed()
+            # check_output should NOT be in originals (skipped)
+            assert "check_output" not in audit._originals
+            # run should still be wrapped
+            assert "run" in audit._originals
+        finally:
+            subprocess.check_output = saved  # type: ignore[assignment]
+            for name, orig in audit._originals.items():
+                setattr(subprocess, name, orig)
+
+
+class TestExtractPatchTargets:
+    """Tests for _extract_patch_targets (lines 263-291)."""
+
+    def _parse_func(self, source: str) -> ast.FunctionDef:
+        tree = ast.parse(textwrap.dedent(source))
+        return tree.body[0]  # type: ignore[return-value]
+
+    def test_patch_object_extracted(self) -> None:
+        """patch.object(module, "name") should extract the short name."""
+        node = self._parse_func(
+            """
+            def test_foo():
+                with patch.object(mymodule, "subprocess"):
+                    mymodule.do_thing()
+            """
+        )
+        targets = _extract_patch_targets(node)
+        assert "subprocess" in targets
+
+    def test_patch_object_with_module_alias(self) -> None:
+        """patch.object with a module alias Name as first arg."""
+        node = self._parse_func(
+            """
+            def test_foo():
+                with patch.object(subprocess, "run"):
+                    subprocess.run(["echo"])
+            """
+        )
+        targets = _extract_patch_targets(node)
+        assert "run" in targets
+
+    def test_with_patch_context_manager_extracted(self) -> None:
+        """with patch("module.func") in function body should be extracted."""
+        node = self._parse_func(
+            """
+            def test_foo():
+                with patch("mymodule.subprocess.run"):
+                    mymodule.do_thing()
+            """
+        )
+        targets = _extract_patch_targets(node)
+        assert "mymodule.subprocess.run" in targets
+        assert "run" in targets
+
+    def test_with_multiple_patch_context_managers(self) -> None:
+        """with patch("a"), patch("b") should extract both."""
+        node = self._parse_func(
+            """
+            def test_foo():
+                with patch("mod.a"), patch("mod.b"):
+                    pass
+            """
+        )
+        targets = _extract_patch_targets(node)
+        assert "mod.a" in targets
+        assert "mod.b" in targets
+        assert "a" in targets
+        assert "b" in targets
+
+    def test_patch_object_non_string_second_arg_ignored(self) -> None:
+        """patch.object with non-string 2nd arg should not crash."""
+        node = self._parse_func(
+            """
+            def test_foo():
+                with patch.object(mymodule, some_var):
+                    pass
+            """
+        )
+        targets = _extract_patch_targets(node)
+        assert targets == set()
+
+
+class TestCallGraph:
+    """Tests for CallGraph building (lines 409, 419-420, 449, 470)."""
+
+    def _make_src(self, tmp_path: Path, files: dict[str, str]) -> Path:
+        src = tmp_path / "src"
+        src.mkdir()
+        for rel, content in files.items():
+            f = src / rel
+            f.parent.mkdir(parents=True, exist_ok=True)
+            f.write_text(textwrap.dedent(content))
+        return src
+
+    def test_ensure_built_cached(self, tmp_path: Path) -> None:
+        """_ensure_built should only build once (cached return)."""
+        src = self._make_src(tmp_path, {"pkg/__init__.py": "", "pkg/mod.py": "def foo():\n    pass\n"})
+        cg = CallGraph(src)
+        cg._ensure_built()
+        assert cg._built is True
+        nodes_before = dict(cg._nodes)
+        # Second call should be a no-op
+        cg._ensure_built()
+        assert cg._nodes == nodes_before
+
+    def test_build_skips_syntax_error(self, tmp_path: Path) -> None:
+        """Files with syntax errors should be skipped, not crash."""
+        src = self._make_src(
+            tmp_path,
+            {
+                "pkg/__init__.py": "",
+                "pkg/broken.py": "def test(:\n  pass\n",
+                "pkg/good.py": "def foo():\n    pass\n",
+            },
+        )
+        cg = CallGraph(src)
+        cg._ensure_built()
+        # good.py's foo should be registered, broken.py skipped
+        assert any("foo" in k for k in cg._nodes)
+
+    def test_build_skips_unicode_decode_error(self, tmp_path: Path) -> None:
+        """Files with invalid UTF-8 should be skipped."""
+        src = tmp_path / "src"
+        src.mkdir()
+        (src / "pkg").mkdir()
+        (src / "pkg" / "__init__.py").write_text("")
+        (src / "pkg" / "binary.py").write_bytes(b"\xff\xfe\x00\xbad bytes")
+        (src / "pkg" / "good.py").write_text("def foo():\n    pass\n")
+        cg = CallGraph(src)
+        cg._ensure_built()
+        assert any("foo" in k for k in cg._nodes)
+
+    def test_scan_node_skips_classdef(self, tmp_path: Path) -> None:
+        """Methods inside classes should NOT be registered."""
+        src = self._make_src(
+            tmp_path,
+            {
+                "pkg/__init__.py": "",
+                "pkg/mod.py": """
+                    class MyClass:
+                        def my_method(self):
+                            subprocess.run(["echo"])
+                    def top_level():
+                        pass
+                """,
+            },
+        )
+        cg = CallGraph(src)
+        cg._ensure_built()
+        # top_level should be registered
+        assert "pkg.mod.top_level" in cg._nodes
+        # my_method should NOT be registered (class body skipped)
+        assert "pkg.mod.my_method" not in cg._nodes
+        assert "my_method" not in cg._by_short
+
+    def test_register_function_records_io_calls(self, tmp_path: Path) -> None:
+        """KNOWN_IO_FUNCTIONS calls should be recorded in io_calls."""
+        src = self._make_src(
+            tmp_path,
+            {
+                "pkg/__init__.py": "",
+                "pkg/mod.py": """
+                    def foo():
+                        get_pat("staging")
+                        load_secrets("prod")
+                """,
+            },
+        )
+        cg = CallGraph(src)
+        cg._ensure_built()
+        node = cg._nodes["pkg.mod.foo"]
+        assert "get_pat" in node.io_calls
+        assert "load_secrets" in node.io_calls
+
+    def test_register_function_records_subprocess_calls(self, tmp_path: Path) -> None:
+        """subprocess.run calls should be recorded in subprocess_calls."""
+        src = self._make_src(
+            tmp_path,
+            {
+                "pkg/__init__.py": "",
+                "pkg/mod.py": """
+                    import subprocess
+                    def foo():
+                        subprocess.run(["echo"])
+                """,
+            },
+        )
+        cg = CallGraph(src)
+        cg._ensure_built()
+        node = cg._nodes["pkg.mod.foo"]
+        assert "subprocess.run" in node.subprocess_calls
+
+
+class TestFindReachableDangerous:
+    """Tests for find_reachable_dangerous (lines 516-580)."""
+
+    def _make_src(self, tmp_path: Path, files: dict[str, str]) -> Path:
+        src = tmp_path / "src"
+        src.mkdir()
+        for rel, content in files.items():
+            f = src / rel
+            f.parent.mkdir(parents=True, exist_ok=True)
+            f.write_text(textwrap.dedent(content))
+        return src
+
+    def test_import_map_resolution(self, tmp_path: Path) -> None:
+        """import_map should resolve target to a precise full name."""
+        src = self._make_src(
+            tmp_path,
+            {
+                "pkg/__init__.py": "",
+                "pkg/mod.py": """
+                    import subprocess
+                    def main():
+                        subprocess.run(["echo"])
+                """,
+            },
+        )
+        cg = CallGraph(src)
+        dangerous = cg.find_reachable_dangerous("main", set(), import_map={"main": "pkg.mod.main"})
+        assert len(dangerous) == 1
+        assert "subprocess" in dangerous[0][1]
+
+    def test_import_map_falls_back_to_short_name(self, tmp_path: Path) -> None:
+        """If import_map value not in nodes, fall back to short name (line 516)."""
+        src = self._make_src(
+            tmp_path,
+            {
+                "pkg/__init__.py": "",
+                "pkg/mod.py": """
+                    import subprocess
+                    def main():
+                        subprocess.run(["echo"])
+                """,
+            },
+        )
+        cg = CallGraph(src)
+        # import_map points to a non-existent full name → fallback to by_short
+        dangerous = cg.find_reachable_dangerous("main", set(), import_map={"main": "nonexistent.pkg.main"})
+        assert len(dangerous) == 1
+
+    def test_no_candidates_returns_empty(self, tmp_path: Path) -> None:
+        """If no candidates found, return empty list (line 526)."""
+        src = self._make_src(tmp_path, {"pkg/__init__.py": ""})
+        cg = CallGraph(src)
+        dangerous = cg.find_reachable_dangerous("nonexistent", set())
+        assert dangerous == []
+
+    def test_fully_qualified_name_candidate(self, tmp_path: Path) -> None:
+        """A fully-qualified target_name in nodes should be used directly (line 519)."""
+        src = self._make_src(
+            tmp_path,
+            {
+                "pkg/__init__.py": "",
+                "pkg/mod.py": """
+                    import subprocess
+                    def main():
+                        subprocess.run(["echo"])
+                """,
+            },
+        )
+        cg = CallGraph(src)
+        dangerous = cg.find_reachable_dangerous("pkg.mod.main", set())
+        assert len(dangerous) == 1
+
+    def test_short_name_fallback(self, tmp_path: Path) -> None:
+        """target_name not in nodes falls back to short name (line 522)."""
+        src = self._make_src(
+            tmp_path,
+            {
+                "pkg/__init__.py": "",
+                "pkg/mod.py": """
+                    import subprocess
+                    def main():
+                        subprocess.run(["echo"])
+                """,
+            },
+        )
+        cg = CallGraph(src)
+        # "pkg.main" is not a full name in nodes, so it falls back to "main"
+        dangerous = cg.find_reachable_dangerous("pkg.main", set())
+        assert len(dangerous) == 1
+
+    def test_visited_prevents_infinite_loop(self, tmp_path: Path) -> None:
+        """Visited set prevents infinite loops (line 535)."""
+        src = self._make_src(
+            tmp_path,
+            {
+                "pkg/__init__.py": "",
+                "pkg/mod.py": """
+                    def a():
+                        b()
+                    def b():
+                        a()
+                        subprocess.run(["echo"])
+                """,
+            },
+        )
+        cg = CallGraph(src)
+        dangerous = cg.find_reachable_dangerous("a", set())
+        assert len(dangerous) == 1
+
+    def test_depth_limit_stops_traversal(self, tmp_path: Path) -> None:
+        """max_depth should stop traversal (line 534)."""
+        src = self._make_src(
+            tmp_path,
+            {
+                "pkg/__init__.py": "",
+                "pkg/mod.py": """
+                    def a():
+                        b()
+                    def b():
+                        c()
+                    def c():
+                        subprocess.run(["echo"])
+                """,
+            },
+        )
+        cg = CallGraph(src)
+        # With max_depth=0, only the direct node is visited
+        dangerous = cg.find_reachable_dangerous("a", set(), max_depth=0)
+        assert dangerous == []
+
+    def test_node_not_found_continues(self, tmp_path: Path) -> None:
+        """If a queued node isn't in _nodes, continue (line 540)."""
+        src = self._make_src(tmp_path, {"pkg/__init__.py": ""})
+        cg = CallGraph(src)
+        # Manually inject a candidate that doesn't exist in nodes
+        cg._by_short["ghost"] = ["pkg.mod.ghost"]
+        dangerous = cg.find_reachable_dangerous("ghost", set())
+        assert dangerous == []
+
+    def test_io_calls_checked(self, tmp_path: Path) -> None:
+        """IO calls should be reported as dangerous (lines 551-554)."""
+        src = self._make_src(
+            tmp_path,
+            {
+                "pkg/__init__.py": "",
+                "pkg/mod.py": """
+                    def main():
+                        get_pat("staging")
+                """,
+            },
+        )
+        cg = CallGraph(src)
+        dangerous = cg.find_reachable_dangerous("main", set())
+        assert len(dangerous) == 1
+        assert "PAT" in dangerous[0][1] or "get_pat" in str(dangerous)
+
+    def test_io_calls_patched_skipped(self, tmp_path: Path) -> None:
+        """Patched IO calls should not be reported."""
+        src = self._make_src(
+            tmp_path,
+            {
+                "pkg/__init__.py": "",
+                "pkg/mod.py": """
+                    def main():
+                        get_pat("staging")
+                """,
+            },
+        )
+        cg = CallGraph(src)
+        dangerous = cg.find_reachable_dangerous("main", {"get_pat"})
+        assert dangerous == []
+
+    def test_patched_helper_skipped_in_enqueue(self, tmp_path: Path) -> None:
+        """A patched helper should not be enqueued (lines 559-560)."""
+        src = self._make_src(
+            tmp_path,
+            {
+                "pkg/__init__.py": "",
+                "pkg/mod.py": """
+                    def main():
+                        run_cmd()
+                    def run_cmd():
+                        subprocess.run(["echo"])
+                """,
+            },
+        )
+        cg = CallGraph(src)
+        # run_cmd is patched → should not traverse into it
+        dangerous = cg.find_reachable_dangerous("main", {"run_cmd"})
+        assert dangerous == []
+
+    def test_same_module_resolution(self, tmp_path: Path) -> None:
+        """Calls within the same module should prefer same-module resolution (lines 566-567)."""
+        src = self._make_src(
+            tmp_path,
+            {
+                "pkg/__init__.py": "",
+                "pkg/mod.py": """
+                    def main():
+                        helper()
+                    def helper():
+                        subprocess.run(["echo"])
+                """,
+            },
+        )
+        cg = CallGraph(src)
+        dangerous = cg.find_reachable_dangerous("main", set())
+        assert len(dangerous) == 1
+
+    def test_short_name_single_match_resolution(self, tmp_path: Path) -> None:
+        """A single global match by short name should be resolved (lines 571-572)."""
+        src = self._make_src(
+            tmp_path,
+            {
+                "pkg/__init__.py": "",
+                "pkg/mod.py": """
+                    def main():
+                        helper()
+                """,
+                "pkg/other.py": """
+                    import subprocess
+                    def helper():
+                        subprocess.run(["echo"])
+                """,
+            },
+        )
+        cg = CallGraph(src)
+        dangerous = cg.find_reachable_dangerous("main", set())
+        assert len(dangerous) == 1
+
+    def test_is_patched_endswith(self, tmp_path: Path) -> None:
+        """_is_patched should match patches ending with .short (line 580)."""
+        src = self._make_src(
+            tmp_path,
+            {
+                "pkg/__init__.py": "",
+                "pkg/mod.py": """
+                    import subprocess
+                    def main():
+                        subprocess.run(["echo"])
+                """,
+            },
+        )
+        cg = CallGraph(src)
+        # "devx.ci.release.subprocess.run" ends with ".run"
+        dangerous = cg.find_reachable_dangerous("main", {"devx.ci.release.subprocess.run"})
+        assert dangerous == []
+
+    def test_is_patched_full_name_match(self) -> None:
+        """_is_patched should match exact full name."""
+        assert CallGraph._is_patched("subprocess.run", "run", {"subprocess.run"}) is True
+
+    def test_is_patched_short_name_match(self) -> None:
+        """_is_patched should match short name in patches."""
+        assert CallGraph._is_patched("subprocess.run", "run", {"run"}) is True
+
+    def test_is_patched_no_match(self) -> None:
+        """_is_patched should return False when not patched."""
+        assert CallGraph._is_patched("subprocess.run", "run", {"other"}) is False
+
+    def test_is_patched_endswith_no_false_positive(self) -> None:
+        """endswith should not match substrings (e.g. 'run' vs 'run_cmd')."""
+        assert CallGraph._is_patched("mod.run_cmd", "run_cmd", {"mod.run"}) is False
+
+
+class TestVisitCallAttributeTarget:
+    """Tests for visit_Call with ast.Attribute target (lines 851-862)."""
+
+    def test_invoke_with_module_func_attribute(self, tmp_path: Path) -> None:
+        """runner.invoke(module.func) should resolve via import_map."""
+        src = tmp_path / "src"
+        src.mkdir()
+        (src / "pkg").mkdir()
+        (src / "pkg" / "__init__.py").write_text("")
+        (src / "pkg" / "cli.py").write_text("import subprocess\ndef main():\n    subprocess.run(['echo'])\n")
+
+        test_file = tmp_path / "test_example.py"
+        test_file.write_text(
+            textwrap.dedent(
+                """
+                from click.testing import CliRunner
+                import pkg.cli as cli_mod
+                class TestExample:
+                    def test_invoke(self) -> None:
+                        runner = CliRunner()
+                        result = runner.invoke(cli_mod.main, [])
+                """
+            )
+        )
+        cg = CallGraph(src)
+        violations = analyze_file(test_file, call_graph=cg)
+        transitive = [v for v in violations if v.category == "transitive-subprocess"]
+        assert len(transitive) == 1
+
+    def test_invoke_with_attribute_no_import_map(self, tmp_path: Path) -> None:
+        """runner.invoke(mod.func) where mod not in import_map uses attr only (line 860)."""
+        src = tmp_path / "src"
+        src.mkdir()
+        (src / "pkg").mkdir()
+        (src / "pkg" / "__init__.py").write_text("")
+        (src / "pkg" / "cli.py").write_text("import subprocess\ndef main():\n    subprocess.run(['echo'])\n")
+
+        test_file = tmp_path / "test_example.py"
+        test_file.write_text(
+            textwrap.dedent(
+                """
+                from click.testing import CliRunner
+                class TestExample:
+                    def test_invoke(self) -> None:
+                        runner = CliRunner()
+                        # unknown_mod not imported, so falls back to attr name
+                        result = runner.invoke(unknown_mod.main, [])
+                """
+            )
+        )
+        cg = CallGraph(src)
+        violations = analyze_file(test_file, call_graph=cg)
+        transitive = [v for v in violations if v.category == "transitive-subprocess"]
+        assert len(transitive) == 1
+
+    def test_invoke_with_attribute_non_name_value(self, tmp_path: Path) -> None:
+        """runner.invoke(get_obj().func) — target.value is not a Name (line 862)."""
+        src = tmp_path / "src"
+        src.mkdir()
+        (src / "pkg").mkdir()
+        (src / "pkg" / "__init__.py").write_text("")
+        (src / "pkg" / "cli.py").write_text("import subprocess\ndef main():\n    subprocess.run(['echo'])\n")
+
+        test_file = tmp_path / "test_example.py"
+        test_file.write_text(
+            textwrap.dedent(
+                """
+                from click.testing import CliRunner
+                class TestExample:
+                    def test_invoke(self) -> None:
+                        runner = CliRunner()
+                        result = runner.invoke(CliRunner().main, [])
+                """
+            )
+        )
+        cg = CallGraph(src)
+        violations = analyze_file(test_file, call_graph=cg)
+        transitive = [v for v in violations if v.category == "transitive-subprocess"]
+        assert len(transitive) == 1
+
+
+class TestIsIntegrationTest:
+    """Tests for _is_integration_test (lines 1076-1080)."""
+
+    def test_marker_based_integration(self) -> None:
+        """A test item with 'integration' in keywords should be detected."""
+        item = MagicMock()
+        item.keywords = {"integration", "test_foo"}
+        item.fspath = "tests/unit/test_foo.py"
+        assert _is_integration_test(item) is True
+
+    def test_path_based_integration(self) -> None:
+        """A test item in an integration/ directory should be detected."""
+        item = MagicMock()
+        item.keywords = {"test_foo"}
+        item.fspath = "tests/integration/test_foo.py"
+        assert _is_integration_test(item) is True
+
+    def test_not_integration_test(self) -> None:
+        """A regular test item should not be detected as integration."""
+        item = MagicMock()
+        item.keywords = {"test_foo"}
+        item.fspath = "tests/unit/test_foo.py"
+        assert _is_integration_test(item) is False
+
+    def test_no_keywords_attr(self) -> None:
+        """An item without keywords attr should use fspath only."""
+        item = MagicMock()
+        item.keywords = {}
+        item.fspath = "tests/unit/test_foo.py"
+        assert _is_integration_test(item) is False
+
+
+class TestLoadTestIsolationConfig:
+    """Tests for _load_test_isolation_config — project-specific rule merging."""
+
+    def test_merges_io_functions(self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+        """Project-specific io_functions are added to KNOWN_IO_FUNCTIONS."""
+        pyproject = tmp_path / "pyproject.toml"
+        pyproject.write_text(
+            '[tool.devx.check_test_isolation]\nio_functions = { "my_custom_io" = "reads from disk" }\n'
+        )
+        monkeypatch.chdir(tmp_path)
+        _load_test_isolation_config()
+        assert "my_custom_io" in KNOWN_IO_FUNCTIONS
+        assert KNOWN_IO_FUNCTIONS["my_custom_io"] == "reads from disk"
+
+    def test_merges_subprocess_helpers(self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+        """Project-specific subprocess_helpers are added."""
+        pyproject = tmp_path / "pyproject.toml"
+        pyproject.write_text(
+            '[tool.devx.check_test_isolation]\nsubprocess_helpers = { "my_sp_helper" = "calls subprocess.run" }\n'
+        )
+        monkeypatch.chdir(tmp_path)
+        _load_test_isolation_config()
+        assert "my_sp_helper" in KNOWN_SUBPROCESS_HELPERS
+
+    def test_merges_helper_internal_calls(self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+        """Project-specific helper_internal_calls are merged."""
+        pyproject = tmp_path / "pyproject.toml"
+        pyproject.write_text(
+            '[tool.devx.check_test_isolation]\nhelper_internal_calls = { "my_helper" = ["subprocess", "run_cmd"] }\n'
+        )
+        monkeypatch.chdir(tmp_path)
+        _load_test_isolation_config()
+        assert "my_helper" in HELPER_INTERNAL_CALLS
+        assert HELPER_INTERNAL_CALLS["my_helper"] == {"subprocess", "run_cmd"}
+
+    def test_merges_io_internal_calls(self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+        """Project-specific io_internal_calls are merged."""
+        pyproject = tmp_path / "pyproject.toml"
+        pyproject.write_text(
+            '[tool.devx.check_test_isolation]\nio_internal_calls = { "my_io_func" = ["open", "yaml"] }\n'
+        )
+        monkeypatch.chdir(tmp_path)
+        _load_test_isolation_config()
+        assert "my_io_func" in IO_INTERNAL_CALLS
+        assert IO_INTERNAL_CALLS["my_io_func"] == {"open", "yaml"}
+
+    def test_merges_heavy_module_imports(self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+        """Project-specific heavy_module_imports are merged."""
+        pyproject = tmp_path / "pyproject.toml"
+        pyproject.write_text('[tool.devx.check_test_isolation]\nheavy_module_imports = { "mymodule" = 150.0 }\n')
+        monkeypatch.chdir(tmp_path)
+        _load_test_isolation_config()
+        assert "mymodule" in HEAVY_MODULE_IMPORTS
+        assert HEAVY_MODULE_IMPORTS["mymodule"] == 150.0
+
+    def test_no_config_section_is_noop(self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+        """Missing [tool.devx.check_test_isolation] section is a no-op."""
+        pyproject = tmp_path / "pyproject.toml"
+        pyproject.write_text('[tool.devx]\nother_key = "value"\n')
+        monkeypatch.chdir(tmp_path)
+        before_io = dict(KNOWN_IO_FUNCTIONS)
+        _load_test_isolation_config()
+        assert before_io == KNOWN_IO_FUNCTIONS
+
+    def test_no_pyproject_is_noop(self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+        """No pyproject.toml at all is a no-op."""
+        monkeypatch.chdir(tmp_path)
+        before = dict(KNOWN_SUBPROCESS_HELPERS)
+        _load_test_isolation_config()
+        assert before == KNOWN_SUBPROCESS_HELPERS
+
+    def test_non_dict_config_is_noop(self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+        """A non-dict check_test_isolation section is a no-op."""
+        pyproject = tmp_path / "pyproject.toml"
+        pyproject.write_text('[tool.devx]\ncheck_test_isolation = "not_a_dict"\n')
+        monkeypatch.chdir(tmp_path)
+        before = dict(HEAVY_MODULE_IMPORTS)
+        _load_test_isolation_config()
+        assert before == HEAVY_MODULE_IMPORTS
+
+    def test_invalid_entry_types_are_skipped(self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+        """Entries with wrong types (non-str values) are silently skipped."""
+        pyproject = tmp_path / "pyproject.toml"
+        pyproject.write_text(
+            "[tool.devx.check_test_isolation]\n"
+            'io_functions = { "good_func" = "desc", "bad_func" = 123 }\n'
+            'heavy_module_imports = { "good_mod" = 100.0, "bad_mod" = "fast" }\n'
+        )
+        monkeypatch.chdir(tmp_path)
+        _load_test_isolation_config()
+        assert "good_func" in KNOWN_IO_FUNCTIONS
+        assert "bad_func" not in KNOWN_IO_FUNCTIONS
+        assert "good_mod" in HEAVY_MODULE_IMPORTS
+        assert "bad_mod" not in HEAVY_MODULE_IMPORTS
+
+    def test_extends_without_replacing_defaults(self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+        """Project config adds to defaults without removing them."""
+        pyproject = tmp_path / "pyproject.toml"
+        pyproject.write_text('[tool.devx.check_test_isolation]\nio_functions = { "project_func" = "project I/O" }\n')
+        monkeypatch.chdir(tmp_path)
+        _load_test_isolation_config()
+        # Default entries still present
+        assert "get_pat" in KNOWN_IO_FUNCTIONS
+        # Project entry added
+        assert "project_func" in KNOWN_IO_FUNCTIONS

tests/unit/test_check_test_speed.py

@@ -10,6 +10,7 @@ from devx.tools.check_test_speed import (
     DEFAULT_MAX_SECONDS,
     DEFAULT_MAX_SINGLE_SECONDS,
     TEST_COMMAND,
+    _ci_scale_limit,
     check_per_test_speed,
     check_speed,
     cli,
@@ -144,7 +145,26 @@ def test_main_module_block() -> None:
         mock_cli.assert_called_once_with([])
 
 
+class TestCiScaleLimit:
+    def test_no_scaling_when_not_ci(self) -> None:
+        with patch("devx.tools.check_test_speed._IS_CI", False):
+            assert _ci_scale_limit(10.0) == 10.0
+            assert _ci_scale_limit(0.5) == 0.5
+
+    def test_scales_when_ci(self) -> None:
+        with patch("devx.tools.check_test_speed._IS_CI", True):
+            with patch("devx.tools.check_test_speed.CI_SCALE_FACTOR", 4.0):
+                assert _ci_scale_limit(10.0) == 40.0
+                assert _ci_scale_limit(0.5) == 2.0
+
+    def test_custom_scale_factor(self) -> None:
+        with patch("devx.tools.check_test_speed._IS_CI", True):
+            with patch("devx.tools.check_test_speed.CI_SCALE_FACTOR", 2.5):
+                assert _ci_scale_limit(10.0) == 25.0
+
+
 class TestMain:
+    @patch("devx.tools.check_test_speed._IS_CI", False)
     @patch("devx.tools.check_test_speed.run_tests")
     @patch("devx.tools.check_test_speed.parse_duration")
     @patch("devx.tools.check_test_speed.check_speed")
@@ -174,6 +194,7 @@ class TestMain:
         mock_parse_per.assert_called_once()
         mock_check_per.assert_called_once_with([], DEFAULT_MAX_SINGLE_SECONDS)
 
+    @patch("devx.tools.check_test_speed._IS_CI", False)
     @patch("devx.tools.check_test_speed.run_tests")
     @patch("devx.tools.check_test_speed.parse_duration")
     def test_slow_total_exits(
@@ -189,6 +210,7 @@ class TestMain:
         assert result.exit_code == 1
         assert "too slow" in result.output.lower()
 
+    @patch("devx.tools.check_test_speed._IS_CI", False)
     @patch("devx.tools.check_test_speed.run_tests")
     @patch("devx.tools.check_test_speed.parse_duration")
     @patch("devx.tools.check_test_speed.check_speed")
@@ -213,6 +235,7 @@ class TestMain:
         assert "Per-test speed check FAILED" in result.output
         assert "test_slow" in result.output
 
+    @patch("devx.tools.check_test_speed._IS_CI", False)
     @patch("devx.tools.check_test_speed.run_tests")
     def test_parse_failure_exits(
         self,
@@ -225,6 +248,7 @@ class TestMain:
         assert result.exit_code == 1
         assert "Could not parse" in result.output
 
+    @patch("devx.tools.check_test_speed._IS_CI", False)
     @patch("devx.tools.check_test_speed.run_tests")
     @patch("devx.tools.check_test_speed.parse_duration")
     @patch("devx.tools.check_test_speed.check_speed")
@@ -248,6 +272,7 @@ class TestMain:
         assert result.exit_code == 0
         mock_check.assert_called_once_with(0.5, 1.5)
 
+    @patch("devx.tools.check_test_speed._IS_CI", False)
     @patch("devx.tools.check_test_speed.run_tests")
     @patch("devx.tools.check_test_speed.parse_duration")
     @patch("devx.tools.check_test_speed.check_speed")
@@ -270,6 +295,7 @@ class TestMain:
         mock_parse_per.assert_not_called()
         mock_check_per.assert_not_called()
 
+    @patch("devx.tools.check_test_speed._IS_CI", False)
     @patch("devx.tools.check_test_speed.run_tests")
     @patch("devx.tools.check_test_speed.parse_duration")
     @patch("devx.tools.check_test_speed.check_speed")
@@ -292,3 +318,32 @@ class TestMain:
         result = runner.invoke(cli, ["--max-single-seconds", "1.0"])
         assert result.exit_code == 0
         mock_check_per.assert_called_once_with([], 1.0)
+
+    @patch("devx.tools.check_test_speed._IS_CI", True)
+    @patch("devx.tools.check_test_speed.CI_SCALE_FACTOR", 4.0)
+    @patch("devx.tools.check_test_speed.run_tests")
+    @patch("devx.tools.check_test_speed.parse_duration")
+    @patch("devx.tools.check_test_speed.check_speed")
+    @patch("devx.tools.check_test_speed.parse_per_test_durations")
+    @patch("devx.tools.check_test_speed.check_per_test_speed")
+    def test_ci_scales_limits(
+        self,
+        mock_check_per: MagicMock,
+        mock_parse_per: MagicMock,
+        mock_check: MagicMock,
+        mock_parse: MagicMock,
+        mock_run: MagicMock,
+    ) -> None:
+        mock_run.return_value = ("out\n", "err\n")
+        mock_parse.return_value = 30.0  # would fail local (10s) but pass CI (40s)
+        mock_parse_per.return_value = []
+        mock_check_per.return_value = []
+
+        runner = CliRunner()
+        result = runner.invoke(cli, [])
+        assert result.exit_code == 0
+        assert "CI environment detected" in result.output
+        assert "scaling limits by 4.0x" in result.output
+        # check_speed called with scaled limit
+        mock_check.assert_called_once_with(30.0, 40.0)
+        mock_check_per.assert_called_once_with([], 2.0)

tests/unit/test_ci_cancel_superseded_runs.py

@@ -0,0 +1,172 @@
+"""Unit tests for devx.ci.cancel_superseded_runs."""
+
+from __future__ import annotations
+
+import json
+import urllib.error
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+import devx.ci.cancel_superseded_runs as mod
+from devx.ci.cancel_superseded_runs import _api_request, cancel_run, list_running_runs, main
+
+_HTTP_NO_CONTENT = mod._HTTP_NO_CONTENT
+_PAGE_SIZE = mod._PAGE_SIZE
+
+
+class TestConstants:
+    def test_http_no_content_is_204(self) -> None:
+        assert _HTTP_NO_CONTENT == 204
+
+    def test_page_size_is_50(self) -> None:
+        assert _PAGE_SIZE == 50
+
+
+class TestApiRequest:
+    def test_returns_empty_for_204(self) -> None:
+        mock_resp = MagicMock()
+        mock_resp.status = _HTTP_NO_CONTENT
+        mock_resp.read.return_value = b""
+        mock_resp.__enter__ = MagicMock(return_value=mock_resp)
+        mock_resp.__exit__ = MagicMock(return_value=None)
+        with patch("urllib.request.urlopen", return_value=mock_resp):
+            result = _api_request("POST", "/repos/test/actions/runs/1/cancel", "tok", "https://x")
+        assert result == {}
+
+    def test_returns_json_for_200(self) -> None:
+        mock_resp = MagicMock()
+        mock_resp.status = 200
+        mock_resp.read.return_value = json.dumps({"id": 1}).encode()
+        mock_resp.__enter__ = MagicMock(return_value=mock_resp)
+        mock_resp.__exit__ = MagicMock(return_value=None)
+        with patch("urllib.request.urlopen", return_value=mock_resp):
+            result = _api_request("GET", "/repos/test/actions/runs", "tok", "https://x")
+        assert result == {"id": 1}
+
+    def test_http_error_raises(self) -> None:
+        err = urllib.error.HTTPError("x", 500, "err", {}, None)
+        err.read = MagicMock(return_value=b"error body")
+        with patch("urllib.request.urlopen", side_effect=err):
+            with pytest.raises(urllib.error.HTTPError):
+                _api_request("GET", "/repos/test/actions/runs", "tok", "https://x")
+
+    def test_url_error_raises(self) -> None:
+        with patch("urllib.request.urlopen", side_effect=urllib.error.URLError("fail")):
+            with pytest.raises(urllib.error.URLError):
+                _api_request("GET", "/repos/test/actions/runs", "tok", "https://x")
+
+
+class TestListRunningRuns:
+    def test_paginates_until_empty(self) -> None:
+        page1 = {"workflow_runs": [{"id": 1}, {"id": 2}], "total_count": 2}
+        page2 = {"workflow_runs": [], "total_count": 2}
+        responses = iter([page1, page2])
+        with patch.object(mod, "_api_request", side_effect=lambda *a, **k: next(responses)):
+            runs = list_running_runs("owner/repo", "tok", "https://x")
+        assert len(runs) == 2
+
+    def test_empty_first_page(self) -> None:
+        with patch.object(mod, "_api_request", return_value={"workflow_runs": [], "total_count": 0}):
+            runs = list_running_runs("owner/repo", "tok", "https://x")
+        assert runs == []
+
+    def test_stops_at_page_size(self) -> None:
+        full_page = {"workflow_runs": [{"id": i} for i in range(_PAGE_SIZE)], "total_count": _PAGE_SIZE + 1}
+        half_page = {"workflow_runs": [{"id": 99}], "total_count": _PAGE_SIZE + 1}
+        responses = iter([full_page, half_page])
+        with patch.object(mod, "_api_request", side_effect=lambda *a, **k: next(responses)):
+            runs = list_running_runs("owner/repo", "tok", "https://x")
+        assert len(runs) == _PAGE_SIZE + 1
+
+    def test_uses_in_progress_status(self) -> None:
+        with patch.object(mod, "_api_request", return_value={"workflow_runs": [], "total_count": 0}) as mock_req:
+            list_running_runs("owner/repo", "tok", "https://x")
+        path = mock_req.call_args.args[1]
+        assert "status=in_progress" in path
+        assert "status=running" not in path
+
+    def test_accepts_bare_list(self) -> None:
+        with patch.object(mod, "_api_request", return_value=[{"id": 1}, {"id": 2}]):
+            runs = list_running_runs("owner/repo", "tok", "https://x")
+        assert len(runs) == 2
+
+
+class TestCancelRun:
+    def test_success_returns_true(self) -> None:
+        with patch.object(mod, "_api_request", return_value={}):
+            assert cancel_run("owner/repo", 123, "tok", "https://x") is True
+
+    def test_http_error_returns_false(self) -> None:
+        with patch.object(mod, "_api_request", side_effect=urllib.error.HTTPError("x", 500, "err", {}, None)):
+            assert cancel_run("owner/repo", 123, "tok", "https://x") is False
+
+
+class TestMain:
+    def test_no_token_exits_zero(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        monkeypatch.delenv("CI_GITEA_API_TOKEN", raising=False)
+        monkeypatch.delenv("CI_GITEA_TOKEN", raising=False)
+        monkeypatch.setattr("sys.argv", ["cancel", "--repo", "o/r", "--current-run-id", "1", "--head-branch", "feat"])
+        assert main() == 0
+
+    def test_no_superseded_runs(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        monkeypatch.setenv("CI_GITEA_API_TOKEN", "tok")
+        monkeypatch.setattr("sys.argv", ["cancel", "--repo", "o/r", "--current-run-id", "10", "--head-branch", "feat"])
+        with patch.object(mod, "list_running_runs", return_value=[]):
+            assert main() == 0
+
+    def test_cancels_superseded(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        monkeypatch.setenv("CI_GITEA_API_TOKEN", "tok")
+        runs = [
+            {"id": 5, "head_branch": "feat"},
+            {"id": 8, "head_branch": "feat"},
+            {"id": 12, "head_branch": "other"},
+        ]
+        monkeypatch.setattr("sys.argv", ["cancel", "--repo", "o/r", "--current-run-id", "10", "--head-branch", "feat"])
+        with patch.object(mod, "list_running_runs", return_value=runs):
+            with patch.object(mod, "cancel_run", return_value=True) as mock_cancel:
+                assert main() == 0
+        cancelled_ids = [call.args[1] for call in mock_cancel.call_args_list]
+        assert cancelled_ids == [5, 8]
+
+    def test_dry_run_does_not_cancel(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        monkeypatch.setenv("CI_GITEA_API_TOKEN", "tok")
+        runs = [{"id": 5, "head_branch": "feat"}]
+        monkeypatch.setattr(
+            "sys.argv",
+            ["cancel", "--repo", "o/r", "--current-run-id", "10", "--head-branch", "feat", "--dry-run"],
+        )
+        with patch.object(mod, "list_running_runs", return_value=runs):
+            with patch.object(mod, "cancel_run", return_value=True) as mock_cancel:
+                assert main() == 0
+        assert mock_cancel.call_count == 0
+
+    def test_cancel_failure_continues(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        monkeypatch.setenv("CI_GITEA_API_TOKEN", "tok")
+        runs = [{"id": 5, "head_branch": "feat"}, {"id": 8, "head_branch": "feat"}]
+        monkeypatch.setattr("sys.argv", ["cancel", "--repo", "o/r", "--current-run-id", "10", "--head-branch", "feat"])
+        with patch.object(mod, "list_running_runs", return_value=runs):
+            with patch.object(mod, "cancel_run", side_effect=[False, True]):
+                assert main() == 0
+
+    def test_404_returns_zero(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        monkeypatch.setenv("CI_GITEA_API_TOKEN", "tok")
+        monkeypatch.setattr("sys.argv", ["cancel", "--repo", "o/r", "--current-run-id", "10", "--head-branch", "feat"])
+        err = urllib.error.HTTPError("x", 404, "Not Found", {}, None)
+        with patch.object(mod, "list_running_runs", side_effect=err):
+            assert main() == 0
+
+    def test_400_returns_zero(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        monkeypatch.setenv("CI_GITEA_API_TOKEN", "tok")
+        monkeypatch.setattr("sys.argv", ["cancel", "--repo", "o/r", "--current-run-id", "10", "--head-branch", "feat"])
+        err = urllib.error.HTTPError("x", 400, "Bad Request", {}, None)
+        with patch.object(mod, "list_running_runs", side_effect=err):
+            assert main() == 0
+
+    def test_500_raises(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        monkeypatch.setenv("CI_GITEA_API_TOKEN", "tok")
+        monkeypatch.setattr("sys.argv", ["cancel", "--repo", "o/r", "--current-run-id", "10", "--head-branch", "feat"])
+        err = urllib.error.HTTPError("x", 500, "Server Error", {}, None)
+        with patch.object(mod, "list_running_runs", side_effect=err):
+            with pytest.raises(urllib.error.HTTPError):
+                main()

tests/unit/test_ci_check_workflow_artifact_deps.py

@@ -0,0 +1,419 @@
+"""Unit tests for devx.ci.check_workflow_artifact_deps."""
+
+from __future__ import annotations
+
+import textwrap
+from pathlib import Path
+
+from click.testing import CliRunner
+
+from devx.ci.check_workflow_artifact_deps import (
+    _check_workflow,
+    _extract_artifact_info,
+    _is_artifact_action,
+    main,
+)
+
+
+class TestIsArtifactAction:
+    def test_upload_action_gitea(self):
+        assert _is_artifact_action("christopherhx/gitea-upload-artifact@v4", ("upload-artifact",))
+
+    def test_upload_action_github(self):
+        assert _is_artifact_action("actions/upload-artifact@v4", ("upload-artifact",))
+
+    def test_download_action(self):
+        assert _is_artifact_action("christopherhx/gitea-download-artifact@v4", ("download-artifact",))
+
+    def test_non_artifact_action(self):
+        assert not _is_artifact_action("actions/checkout@v4", ("upload-artifact",))
+
+    def test_empty_string(self):
+        assert not _is_artifact_action("", ("upload-artifact",))
+
+    def test_case_insensitive(self):
+        assert _is_artifact_action("Actions/Upload-Artifact@v4", ("upload-artifact",))
+
+
+class TestExtractArtifactInfo:
+    def test_uploads_and_downloads(self):
+        import yaml
+
+        workflow_yaml = textwrap.dedent("""
+            jobs:
+              producer:
+                steps:
+                  - name: Upload config
+                    uses: christopherhx/gitea-upload-artifact@v4
+                    with:
+                      name: config-${{ github.run_id }}
+              consumer:
+                needs: [producer]
+                steps:
+                  - name: Download config
+                    uses: christopherhx/gitea-download-artifact@v4
+                    with:
+                      name: config-${{ github.run_id }}
+        """).strip()
+        wf = yaml.safe_load(workflow_yaml)
+        uploads, downloads = _extract_artifact_info(wf)
+        assert uploads == {"config-${{ github.run_id }}": ["producer"]}
+        assert downloads == [("consumer", "config-${{ github.run_id }}", "Download config")]
+
+    def test_no_artifacts(self):
+        import yaml
+
+        workflow_yaml = textwrap.dedent("""
+            jobs:
+              build:
+                steps:
+                  - name: Checkout
+                    uses: actions/checkout@v4
+        """).strip()
+        wf = yaml.safe_load(workflow_yaml)
+        uploads, downloads = _extract_artifact_info(wf)
+        assert uploads == {}
+        assert downloads == []
+
+    def test_multiple_uploaders_same_artifact(self):
+        import yaml
+
+        workflow_yaml = textwrap.dedent("""
+            jobs:
+              producer-a:
+                steps:
+                  - uses: christopherhx/gitea-upload-artifact@v4
+                    with:
+                      name: shared
+              producer-b:
+                steps:
+                  - uses: christopherhx/gitea-upload-artifact@v4
+                    with:
+                      name: shared
+        """).strip()
+        wf = yaml.safe_load(workflow_yaml)
+        uploads, downloads = _extract_artifact_info(wf)
+        assert uploads == {"shared": ["producer-a", "producer-b"]}
+
+    def test_step_without_name(self):
+        import yaml
+
+        workflow_yaml = textwrap.dedent("""
+            jobs:
+              producer:
+                steps:
+                  - uses: christopherhx/gitea-upload-artifact@v4
+                    with:
+                      name: data
+              consumer:
+                needs: [producer]
+                steps:
+                  - uses: christopherhx/gitea-download-artifact@v4
+                    with:
+                      name: data
+        """).strip()
+        wf = yaml.safe_load(workflow_yaml)
+        uploads, downloads = _extract_artifact_info(wf)
+        assert downloads == [("consumer", "data", "")]
+
+    def test_upload_without_name_skipped(self):
+        import yaml
+
+        workflow_yaml = textwrap.dedent("""
+            jobs:
+              producer:
+                steps:
+                  - uses: christopherhx/gitea-upload-artifact@v4
+                    with:
+                      path: ./dist
+        """).strip()
+        wf = yaml.safe_load(workflow_yaml)
+        uploads, downloads = _extract_artifact_info(wf)
+        assert uploads == {}
+
+
+class TestCheckWorkflow:
+    def test_valid_dependency(self, tmp_path: Path):
+        workflow_yaml = textwrap.dedent("""
+            jobs:
+              producer:
+                steps:
+                  - name: Upload config
+                    uses: christopherhx/gitea-upload-artifact@v4
+                    with:
+                      name: config
+              consumer:
+                needs: [producer]
+                steps:
+                  - name: Download config
+                    uses: christopherhx/gitea-download-artifact@v4
+                    with:
+                      name: config
+        """).strip()
+        f = tmp_path / "test.yml"
+        f.write_text(workflow_yaml)
+        assert _check_workflow(f) == []
+
+    def test_missing_dependency(self, tmp_path: Path):
+        workflow_yaml = textwrap.dedent("""
+            jobs:
+              producer:
+                steps:
+                  - name: Upload config
+                    uses: christopherhx/gitea-upload-artifact@v4
+                    with:
+                      name: config
+              consumer:
+                needs: [other-job]
+                steps:
+                  - name: Download config
+                    uses: christopherhx/gitea-download-artifact@v4
+                    with:
+                      name: config
+        """).strip()
+        f = tmp_path / "test.yml"
+        f.write_text(workflow_yaml)
+        errors = _check_workflow(f)
+        assert len(errors) == 1
+        assert "consumer" in errors[0]
+        assert "producer" in errors[0]
+
+    def test_no_needs_at_all(self, tmp_path: Path):
+        workflow_yaml = textwrap.dedent("""
+            jobs:
+              producer:
+                steps:
+                  - uses: christopherhx/gitea-upload-artifact@v4
+                    with:
+                      name: data
+              consumer:
+                steps:
+                  - uses: christopherhx/gitea-download-artifact@v4
+                    with:
+                      name: data
+        """).strip()
+        f = tmp_path / "test.yml"
+        f.write_text(workflow_yaml)
+        errors = _check_workflow(f)
+        assert len(errors) == 1
+        assert "consumer" in errors[0]
+
+    def test_artifact_not_uploaded_in_workflow(self, tmp_path: Path):
+        workflow_yaml = textwrap.dedent("""
+            jobs:
+              consumer:
+                steps:
+                  - name: Download external
+                    uses: christopherhx/gitea-download-artifact@v4
+                    with:
+                      name: external-artifact
+        """).strip()
+        f = tmp_path / "test.yml"
+        f.write_text(workflow_yaml)
+        assert _check_workflow(f) == []
+
+    def test_multiple_uploaders_one_in_needs(self, tmp_path: Path):
+        workflow_yaml = textwrap.dedent("""
+            jobs:
+              producer-a:
+                steps:
+                  - uses: christopherhx/gitea-upload-artifact@v4
+                    with:
+                      name: shared
+              producer-b:
+                steps:
+                  - uses: christopherhx/gitea-upload-artifact@v4
+                    with:
+                      name: shared
+              consumer:
+                needs: [producer-a, other]
+                steps:
+                  - uses: christopherhx/gitea-download-artifact@v4
+                    with:
+                      name: shared
+        """).strip()
+        f = tmp_path / "test.yml"
+        f.write_text(workflow_yaml)
+        assert _check_workflow(f) == []
+
+    def test_string_needs(self, tmp_path: Path):
+        workflow_yaml = textwrap.dedent("""
+            jobs:
+              producer:
+                steps:
+                  - uses: christopherhx/gitea-upload-artifact@v4
+                    with:
+                      name: data
+              consumer:
+                needs: producer
+                steps:
+                  - uses: christopherhx/gitea-download-artifact@v4
+                    with:
+                      name: data
+        """).strip()
+        f = tmp_path / "test.yml"
+        f.write_text(workflow_yaml)
+        assert _check_workflow(f) == []
+
+    def test_needs_null(self, tmp_path: Path):
+        workflow_yaml = textwrap.dedent("""
+            jobs:
+              producer:
+                steps:
+                  - uses: christopherhx/gitea-upload-artifact@v4
+                    with:
+                      name: data
+              consumer:
+                needs: null
+                steps:
+                  - uses: christopherhx/gitea-download-artifact@v4
+                    with:
+                      name: data
+        """).strip()
+        f = tmp_path / "test.yml"
+        f.write_text(workflow_yaml)
+        errors = _check_workflow(f)
+        assert len(errors) == 1
+        assert "consumer" in errors[0]
+
+    def test_invalid_yaml(self, tmp_path: Path):
+        f = tmp_path / "test.yml"
+        f.write_text("jobs: [invalid yaml: {")
+        errors = _check_workflow(f)
+        assert len(errors) == 1
+        assert "cannot parse YAML" in errors[0]
+
+    def test_not_a_dict(self, tmp_path: Path):
+        f = tmp_path / "test.yml"
+        f.write_text("just a string")
+        errors = _check_workflow(f)
+        assert len(errors) == 1
+        assert "not a valid workflow" in errors[0]
+
+    def test_no_jobs(self, tmp_path: Path):
+        f = tmp_path / "test.yml"
+        f.write_text("name: empty\non: push\n")
+        assert _check_workflow(f) == []
+
+    def test_continue_on_error_guard(self, tmp_path: Path):
+        workflow_yaml = textwrap.dedent("""
+            jobs:
+              producer:
+                steps:
+                  - name: Upload config
+                    uses: christopherhx/gitea-upload-artifact@v4
+                    with:
+                      name: config
+              consumer:
+                needs: [other-job]
+                steps:
+                  - name: Download config
+                    continue-on-error: true
+                    uses: christopherhx/gitea-download-artifact@v4
+                    with:
+                      name: config
+        """).strip()
+        f = tmp_path / "test.yml"
+        f.write_text(workflow_yaml)
+        assert _check_workflow(f) == []
+
+    def test_continue_on_error_false_still_errors(self, tmp_path: Path):
+        workflow_yaml = textwrap.dedent("""
+            jobs:
+              producer:
+                steps:
+                  - name: Upload config
+                    uses: christopherhx/gitea-upload-artifact@v4
+                    with:
+                      name: config
+              consumer:
+                needs: [other-job]
+                steps:
+                  - name: Download config
+                    continue-on-error: false
+                    uses: christopherhx/gitea-download-artifact@v4
+                    with:
+                      name: config
+        """).strip()
+        f = tmp_path / "test.yml"
+        f.write_text(workflow_yaml)
+        errors = _check_workflow(f)
+        assert len(errors) == 1
+        assert "consumer" in errors[0]
+
+    def test_job_with_no_steps(self, tmp_path: Path):
+        workflow_yaml = textwrap.dedent("""
+            jobs:
+              empty:
+                runs-on: docker
+        """).strip()
+        f = tmp_path / "test.yml"
+        f.write_text(workflow_yaml)
+        assert _check_workflow(f) == []
+
+
+class TestMain:
+    def test_passes_when_valid(self, tmp_path: Path):
+        workflow_yaml = textwrap.dedent("""
+            jobs:
+              producer:
+                steps:
+                  - uses: christopherhx/gitea-upload-artifact@v4
+                    with:
+                      name: data
+              consumer:
+                needs: [producer]
+                steps:
+                  - uses: christopherhx/gitea-download-artifact@v4
+                    with:
+                      name: data
+        """).strip()
+        f = tmp_path / "test.yml"
+        f.write_text(workflow_yaml)
+        runner = CliRunner()
+        result = runner.invoke(main, ["--workflows-dir", str(tmp_path)])
+        assert result.exit_code == 0
+        assert "OK" in result.output
+
+    def test_fails_when_missing_dep(self, tmp_path: Path):
+        workflow_yaml = textwrap.dedent("""
+            jobs:
+              producer:
+                steps:
+                  - uses: christopherhx/gitea-upload-artifact@v4
+                    with:
+                      name: data
+              consumer:
+                steps:
+                  - uses: christopherhx/gitea-download-artifact@v4
+                    with:
+                      name: data
+        """).strip()
+        f = tmp_path / "test.yml"
+        f.write_text(workflow_yaml)
+        runner = CliRunner()
+        result = runner.invoke(main, ["--workflows-dir", str(tmp_path)])
+        assert result.exit_code == 1
+        assert "FAIL" in result.output
+        assert "consumer" in result.output
+
+    def test_specific_workflow_file(self, tmp_path: Path):
+        workflow_yaml = textwrap.dedent("""
+            jobs:
+              producer:
+                steps:
+                  - uses: christopherhx/gitea-upload-artifact@v4
+                    with:
+                      name: data
+              consumer:
+                needs: [producer]
+                steps:
+                  - uses: christopherhx/gitea-download-artifact@v4
+                    with:
+                      name: data
+        """).strip()
+        f = tmp_path / "test.yml"
+        f.write_text(workflow_yaml)
+        runner = CliRunner()
+        result = runner.invoke(main, ["--workflow", str(f)])
+        assert result.exit_code == 0