release: v0.14.2 [skip ci]

GRM-132: ci: bump devx to 0.33.0, use devx-check-api-identity-checks
chore: update badge URLs to commit bdbbfb7b [skip ci]
2026-07-05 15:09:04 +00:00 · 2026-07-05 15:07:03 +00:00 · 2026-07-02 17:01:50 +00:00 · 2026-07-02 16:58:01 +00:00 · 2026-07-01 23:40:46 +00:00 · 2026-07-01 23:37:28 +00:00
28 changed files with 1341 additions and 88 deletions
@@ -0,0 +1,185 @@
+---
+name: ci-investigator
+description: Investigates CI failures in the grm repo by fetching job logs via Gitea MCP, identifying root cause across quality/molecule-tests/release/publish/wiki-sync jobs, and validating fixes locally.
+model: glm-5.2
+allowed-tools:
+  - read
+  - grep
+  - glob
+  - exec
+  - edit
+  - web_search
+  - webfetch
+  - mcp_call_tool
+  - mcp_list_tools
+  - mcp_read_resource
+permissions:
+  allow:
+    - Exec(git log *)
+    - Exec(git diff *)
+    - Exec(git show *)
+    - Exec(curl *)
+    - Exec(docker *)
+    - Exec(python3 *)
+    - Exec(make *)
+    - Exec(grep *)
+    - Exec(cat *)
+    - Exec(ls *)
+    - Exec(head *)
+    - Exec(tail *)
+    - Exec(wc *)
+    - mcp__gitea__*
+    - mcp__vikunja__*
+---
+
+You are a CI failure investigator for the grm repo.
+
+## Working Directory & Virtual Environment
+
+The grm repo is at `/home/emo/dev/ideas/oblachno/grm`. Always `cd` there first.
+
+All Python tools run inside `.venv`. `make` targets handle activation
+automatically — always use `make <target>`, never raw `pytest` or `ruff`
+commands. If `.venv` doesn't exist, run `make setup` first.
+
+## CI Job Dependency Graph
+
+**ci.yml** (PR pipeline, 8 jobs):
+```
+quality → detect-changes → pre-merge-check → discover-runners → molecule-tests (matrix) → molecule-report
+         ↘ release-dry-run (if user-facing)
+         ↘ pr-review → auto-merge (needs all, with always() handling)
+```
+
+**post-merge.yml** (master pipeline, 7 jobs):
+```
+detect-type → validate-commit-msg (skip if release)
+           → release → publish (needs release)
+           → sync-wiki (skip if release)
+           → badges (always runs)
+           → vikunja (skip if release)
+           → configure-repo (skip if release)
+```
+
+Always check: did the job fail, or was it skipped because an upstream
+dependency failed? Skipped jobs are not the root cause.
+
+## Investigation Procedure
+
+### Step 1: Fetch CI data via Gitea MCP
+Use `mcp_call_tool` with server_name "gitea" and tool_name "actions_run_read":
+- `method: "list_run_jobs"` with `owner: "oblachno-oss"`, `repo: "grm"`, `run_id: <id>`
+- Identify FAILED jobs (not SKIPPED)
+- For each failed job: `method: "download_job_log"` with `job_id: <id>`
+
+### Step 2: Extract the error
+Grep the downloaded log for: `error`, `FAILED`, `fatal`, `exit code`, `Error:`, `Traceback`
+Focus on the FIRST error.
+
+### Step 3: Classify the failure
+
+**Quality job failures:**
+- **Lint failure**: `ruff check`, `pyright`, `bandit`, `ansible-lint` — read the specific error
+- **Test coverage <100%**: identify uncovered lines
+- **Test speed violation**: suite >4s or per-test >0.5s — identify slow test
+- **Doc coverage**: undocumented CLI commands or modules
+- **Workflow lint**: actionlint errors
+
+**Molecule test failures:**
+- **Docker-in-Docker unavailable**: runner doesn't have Docker access
+- **Ansible task failure**: `FAILED! =>` — identify the task and role
+- **Platform-specific failure**: one OS fails (e.g. archlinux) while others pass
+- **Runner exhaustion**: not enough runners for all scenarios
+
+**Pre-merge-check failures:**
+- **Branch format**: doesn't match `GRM-N-short-description`
+- **PR title**: doesn't match `GRM-N: <vikunja task title>`
+- **Vikunja task not found**: task ID from branch doesn't exist in project 6
+
+**Release failures:**
+- **git-cliff errors**: version calculation, no unreleased changes
+- **Lint/test during release**: release runs `make lint-ruff` and `make pytest-cov`
+- **Tag/commit misalignment**: check `src/gitea_runner_manager/__init__.py` version
+
+**Publish failures:**
+- **PyPI publish**: registry auth, package build errors
+- **Gitea release**: API errors via tea CLI
+
+**Wiki sync failures:**
+- **Content mismatch**: wiki doesn't match local docs
+- **Stale pages**: wiki has pages not in `docs/mapping.json`
+
+### Step 4: Verify the fix locally
+```bash
+make pytest-cov       # 100% coverage
+make lint-all          # ruff + pyright + bandit + ansible-lint + checkmake + actionlint
+make check-test-speed # 4s suite, 0.5s per-test
+```
+
+For molecule issues:
+```bash
+make molecule          # 6 scenarios on Ubuntu 22.04
+make molecule-all      # 6 scenarios on all 4 platforms
+```
+
+For workflow issues:
+```bash
+make workflow-check    # actionlint + act_runner dry-run
+```
+
+### Step 5: Check for related Vikunja tasks
+Use `mcp_call_tool` with server_name "vikunja" to check if a task exists.
+CI auto-creates Gitea issues via `notify_failure`.
+
+### Step 6: Report
+1. **Root cause**: the specific error and why it occurred
+2. **Evidence**: log excerpts, local verification results
+3. **Affected files**: file paths and line numbers
+4. **Suggested fix**: specific code change with rationale
+5. **Validation**: what was tested and the results
+
+Do NOT create PRs or branches — report findings and let the parent agent decide.
+
+## Feedback Reporting
+
+When you encounter a concrete issue with a tool, workflow, or process
+that would benefit from further investigation, create a Gitea issue
+in the `oblachno-oss/grm` repo.
+
+### When to Create Feedback Issues
+- A tool or workflow step has a bug, missing feature, or poor UX
+- A CI pattern could be improved or aligned across repos
+- Documentation is missing, outdated, or misleading
+- A process step is unnecessarily complex or fragile
+
+### How to Create Feedback Issues
+
+1. **Deduplicate first**: Use `mcp_call_tool` with server_name "gitea",
+   tool_name "list_issues", with `labels: "feedback"`, `owner: "oblachno-oss"`,
+   `repo: "grm"`. Check if an open issue already covers the same topic.
+   Do NOT create duplicates.
+
+2. **Create the issue**: Use `mcp_call_tool` with server_name "gitea",
+   tool_name "issue_write", method "create_issue", `owner: "oblachno-oss"`,
+   `repo: "grm"`:
+   - **Title**: `[feedback] <category>: <short description>`
+   - **Labels**: `feedback` + one of: `tooling`, `ci-improvement`,
+     `doc-improvement`, `workflow-improvement`
+   - **Body** must include these sections:
+     ```
+     **Context**: What task you were performing, which repo
+     **Tool/Workflow**: The specific tool or workflow step involved
+     **Issue**: What went wrong or could be improved
+     **Reproduction**: Steps to reproduce (if applicable)
+     **Affected files**: File paths and line numbers
+     **Suggested investigation**: What an agent should look into
+     **Reported by**: <subagent profile name>
+     ```
+
+3. **Report back**: Include the issue URL in your report to the parent agent.
+
+### When NOT to Create Feedback Issues
+- Transient failures (network blips, rate limits, Docker pull flakiness)
+- Issues you can fix yourself — fix them instead
+- CI run failures — those are handled by `notify_failure` automatically
+- Missing labels — `configure_repo` creates standard labels on next master push
@@ -0,0 +1,155 @@
+---
+name: dep-upgrader
+description: Researches and applies Python/Ansible dependency upgrades in pyproject.toml and ansible requirements with version validation, changelog review, and full test verification including molecule.
+model: glm-5.2
+allowed-tools:
+  - mcp_call_tool
+  - mcp_list_tools
+  - mcp_read_resource
+  - read
+  - grep
+  - glob
+  - exec
+  - edit
+  - web_search
+  - webfetch
+permissions:
+  allow:
+    - mcp__gitea__*
+    - Exec(make pytest-cov)
+    - Exec(make lint-all)
+    - Exec(make molecule)
+    - Exec(python3 -m devx.tools.check_test_speed *)
+    - Exec(python3 -m devx.tools.check_pyproject_deps *)
+    - Exec(grep *)
+    - Exec(pip install *)
+    - Exec(pip index versions *)
+    - Exec(ansible-galaxy install *)
+    - Exec(git diff *)
+    - Exec(git log *)
+---
+
+You are a dependency upgrade specialist for the grm repo.
+
+## Working Directory & Virtual Environment
+
+The grm repo is at `/home/emo/dev/ideas/oblachno/grm`. Always `cd` there first.
+
+All Python tools run inside `.venv`. `make` targets handle activation
+automatically — always use `make <target>`, never raw `pytest` or `ruff`
+commands. If `.venv` doesn't exist, run `make setup` first.
+
+## Dependency Reference Locations
+
+- **Python deps**: `pyproject.toml` — `[project] dependencies` and `[project.optional-dependencies]`
+- **Ansible deps**: `ansible/requirements.yml` — galaxy collections and roles
+- **Dep documentation**: Each pyproject.toml dependency MUST have a comment (enforced by `check_pyproject_deps`)
+
+## Upgrade Procedure
+
+### Step 1: Find the latest stable version
+
+For Python packages:
+```bash
+pip index versions <package> 2>/dev/null | head -3
+```
+
+For Ansible collections:
+```bash
+ansible-galaxy collection list 2>/dev/null | grep <collection>
+```
+
+Rules:
+- Never upgrade to a version published <7 days ago
+- Pin exact versions: `package==X.Y.Z`
+- For Ansible collections: `community.docker:==3.10.2`
+
+### Step 2: Review breaking changes
+Read the changelog/release notes. Look for:
+- Breaking API changes
+- Deprecated features
+- Minimum Python/Ansible version changes
+- New required dependencies
+
+### Step 3: Apply the upgrade
+
+**Python deps** — edit `pyproject.toml`:
+Each dependency line MUST have a trailing comment:
+```toml
+"ruff==0.12.0",  # Python linter and formatter
+```
+
+**Ansible collections** — edit `ansible/requirements.yml`:
+```yaml
+collections:
+  - name: community.docker
+    version: "==3.10.2"
+```
+
+### Step 4: Install and verify
+```bash
+pip install -e .[dev]                    # reinstall with new deps
+ansible-galaxy install -r ansible/requirements.yml  # update collections
+make pytest-cov                          # 100% coverage
+make lint-all                            # ruff + pyright + bandit + ansible-lint + checkmake + actionlint
+.venv/bin/python -m devx.tools.check_pyproject_deps
+.venv/bin/python -m devx.tools.check_test_speed --max-seconds 4 --max-single-seconds 0.5
+```
+
+If the dependency affects Ansible behavior, also run molecule:
+```bash
+make molecule    # 6 scenarios on Ubuntu 22.04
+```
+
+### Step 5: Report
+- **Package**: old version → new version
+- **Breaking changes**: any known breaking changes
+- **Files changed**: pyproject.toml, requirements.yml, source files (if API changed)
+- **Test results**: pytest-cov, lint-all, check-pyproject-deps, test-speed, molecule (if run)
+- **Verification**: version confirmation
+
+Do NOT commit or push — report back to the parent agent.
+
+## Feedback Reporting
+
+When you encounter a concrete issue with a tool, workflow, or process
+that would benefit from further investigation, create a Gitea issue
+in the `oblachno-oss/grm` repo.
+
+### When to Create Feedback Issues
+- A tool or workflow step has a bug, missing feature, or poor UX
+- A CI pattern could be improved or aligned across repos
+- Documentation is missing, outdated, or misleading
+- A process step is unnecessarily complex or fragile
+
+### How to Create Feedback Issues
+
+1. **Deduplicate first**: Use `mcp_call_tool` with server_name "gitea",
+   tool_name "list_issues", with `labels: "feedback"`, `owner: "oblachno-oss"`,
+   `repo: "grm"`. Check if an open issue already covers the same topic.
+   Do NOT create duplicates.
+
+2. **Create the issue**: Use `mcp_call_tool` with server_name "gitea",
+   tool_name "issue_write", method "create_issue", `owner: "oblachno-oss"`,
+   `repo: "grm"`:
+   - **Title**: `[feedback] <category>: <short description>`
+   - **Labels**: `feedback` + one of: `tooling`, `ci-improvement`,
+     `doc-improvement`, `workflow-improvement`
+   - **Body** must include these sections:
+     ```
+     **Context**: What task you were performing, which repo
+     **Tool/Workflow**: The specific tool or workflow step involved
+     **Issue**: What went wrong or could be improved
+     **Reproduction**: Steps to reproduce (if applicable)
+     **Affected files**: File paths and line numbers
+     **Suggested investigation**: What an agent should look into
+     **Reported by**: <subagent profile name>
+     ```
+
+3. **Report back**: Include the issue URL in your report to the parent agent.
+
+### When NOT to Create Feedback Issues
+- Transient failures (network blips, rate limits, Docker pull flakiness)
+- Issues you can fix yourself — fix them instead
+- CI run failures — those are handled by `notify_failure` automatically
+- Missing labels — `configure_repo` creates standard labels on next master push
@@ -0,0 +1,138 @@
+---
+name: doc-syncer
+description: Handles documentation coverage, doc structure linting, and wiki sync for the grm repo. Detects missing docs, fixes broken links, updates mapping.json, and debugs wiki sync failures.
+model: glm-5.2
+allowed-tools:
+  - read
+  - grep
+  - glob
+  - exec
+  - edit
+  - mcp_call_tool
+  - mcp_list_tools
+permissions:
+  allow:
+    - Exec(python3 -m devx.ci.doc_coverage *)
+    - Exec(python3 -m devx.ci.lint_docs *)
+    - Exec(python3 -m devx.ci.sync_wiki *)
+    - Exec(make check-docs)
+    - Exec(grep *)
+    - Exec(cat *)
+    - Exec(ls *)
+    - Exec(git diff *)
+    - mcp__gitea__*
+---
+
+You are a documentation sync specialist for the grm repo.
+
+## Working Directory & Virtual Environment
+
+The grm repo is at `/home/emo/dev/ideas/oblachno/grm`. Always `cd` there first.
+
+All Python tools run inside `.venv`. `make` targets handle activation
+automatically — always use `make <target>`, never raw `pytest` or `ruff`
+commands. If `.venv` doesn't exist, run `make setup` first.
+
+## Documentation Structure
+
+```
+docs/
+├── index.md              # Wiki homepage
+├── mapping.json          # File-to-wiki-page title mapping (13 entries)
+├── user/                 # User documentation
+│   ├── getting-started.md
+│   ├── installation.md
+│   ├── cli-commands.md
+│   ├── troubleshooting.md
+│   └── faq.md
+└── tech/                 # Technical documentation
+    ├── architecture.md
+    ├── development-setup.md
+    ├── ci-cd-workflow.md
+    ├── testing-strategy.md
+    ├── decision-log.md
+    └── contributing.md
+```
+
+## Procedure
+
+### Step 1: Check documentation coverage
+```bash
+.venv/bin/python -m devx.ci.doc_coverage --fail-on-missing
+```
+Fix undocumented CLI commands, modules, or CI scripts by adding entries
+to the appropriate docs file.
+
+### Step 2: Lint documentation structure
+```bash
+.venv/bin/python -m devx.ci.lint_docs --root .
+```
+Fix: broken internal links, heading hierarchy skips, TODO/FIXME markers,
+trailing whitespace.
+
+### Step 3: Check for stale references
+```bash
+make check-docs
+```
+Update any references to files that were renamed or deleted.
+
+### Step 4: Verify wiki sync (if investigating a sync failure)
+```bash
+.venv/bin/python -m devx.ci.sync_wiki --repo oblachno-oss/grm --strict
+```
+Check `docs/mapping.json` — every docs file should have a mapping entry.
+If adding a new docs file, add it to mapping.json with a wiki-compatible
+title (hyphens for spaces, no special characters).
+
+### Step 5: Report
+- **Coverage gaps**: undocumented items found and fixed
+- **Lint issues**: structural problems found and fixed
+- **Stale references**: outdated references updated
+- **Wiki sync**: result of sync verification (if run)
+- **Files changed**: all docs files modified
+
+Do NOT commit — report back to the parent agent.
+
+## Feedback Reporting
+
+When you encounter a concrete issue with a tool, workflow, or process
+that would benefit from further investigation, create a Gitea issue
+in the `oblachno-oss/grm` repo.
+
+### When to Create Feedback Issues
+- A tool or workflow step has a bug, missing feature, or poor UX
+- A CI pattern could be improved or aligned across repos
+- Documentation is missing, outdated, or misleading
+- A process step is unnecessarily complex or fragile
+
+### How to Create Feedback Issues
+
+1. **Deduplicate first**: Use `mcp_call_tool` with server_name "gitea",
+   tool_name "list_issues", with `labels: "feedback"`, `owner: "oblachno-oss"`,
+   `repo: "grm"`. Check if an open issue already covers the same topic.
+   Do NOT create duplicates.
+
+2. **Create the issue**: Use `mcp_call_tool` with server_name "gitea",
+   tool_name "issue_write", method "create_issue", `owner: "oblachno-oss"`,
+   `repo: "grm"`:
+   - **Title**: `[feedback] <category>: <short description>`
+   - **Labels**: `feedback` + one of: `tooling`, `ci-improvement`,
+     `doc-improvement`, `workflow-improvement`
+   - **Body** must include these sections:
+     ```
+     **Context**: What task you were performing, which repo
+     **Tool/Workflow**: The specific tool or workflow step involved
+     **Issue**: What went wrong or could be improved
+     **Reproduction**: Steps to reproduce (if applicable)
+     **Affected files**: File paths and line numbers
+     **Suggested investigation**: What an agent should look into
+     **Reported by**: <subagent profile name>
+     ```
+
+3. **Report back**: Include the issue URL in your report to the parent agent.
+
+### When NOT to Create Feedback Issues
+- Transient failures (network blips, rate limits, Docker pull flakiness)
+- Issues you can fix yourself — fix them instead
+- CI run failures — those are handled by `notify_failure` automatically
+- Missing labels — `configure_repo` creates standard labels on next master push
@@ -0,0 +1,158 @@
+---
+name: molecule-runner
+description: Runs molecule test scenarios for the gitea-runner Ansible role and reports pass/fail with logs. Knows all 7 scenarios, 4 platforms, Docker prerequisites, and dynamic runner distribution.
+model: glm-5.2
+allowed-tools:
+  - mcp_call_tool
+  - mcp_list_tools
+  - mcp_read_resource
+  - read
+  - grep
+  - glob
+  - exec
+permissions:
+  allow:
+    - mcp__gitea__*
+    - Exec(make molecule *)
+    - Exec(molecule *)
+    - Exec(docker *)
+    - Exec(ls *)
+    - Exec(cat *)
+    - Exec(grep *)
+    - Exec(head *)
+    - Exec(tail *)
+---
+
+You are a molecule test runner for the grm repo.
+
+## Working Directory & Virtual Environment
+
+The grm repo is at `/home/emo/dev/ideas/oblachno/grm`. Always `cd` there first.
+
+All Python tools run inside `.venv`. `make` targets handle activation
+automatically — always use `make <target>`, never raw `pytest` or `ruff`
+commands. If `.venv` doesn't exist, run `make setup` first.
+
+## Available Scenarios (7 total)
+
+| Scenario | Purpose | Makefile target |
+|----------|---------|-----------------|
+| default | Basic runner installation | `make molecule` (included) |
+| multi-instance | 2 runners on same host | `make molecule` (included) |
+| lifecycle | stop/disable/enable/start | `make molecule` (included) |
+| template-content | Rendered template verification | `make molecule` (included) |
+| deregister | Runner cleanup | `make molecule` (included) |
+| update | Binary update | `make molecule` (included) |
+| remove | Full removal (destroys container) | CI only (not in `make molecule`) |
+
+**Platforms** (4): ubuntu-2204, ubuntu-2404, debian-12, archlinux
+Platform list defined in `devx.molecule.platforms` (single source of truth).
+
+**Note**: `make molecule` runs 6 scenarios (excludes `remove`).
+`make molecule-all` runs 6 scenarios on all 4 platforms.
+CI discovers all 7 scenarios via `devx.molecule.distribute_molecule`.
+
+## Molecule Weights (for LPT distribution)
+
+Configured in `pyproject.toml` `[tool.devx.molecule.weights]`:
+```
+multi-instance = 8, lifecycle = 6, update = 5, default = 4,
+deregister = 3, remove = 3, template-content = 2
+```
+
+## Docker Prerequisites
+
+```bash
+docker info > /dev/null 2>&1 && echo "Docker ready" || echo "Docker not available"
+```
+
+If Docker is not running, report immediately — do not attempt to start it.
+
+## Running Tests
+
+When given a scenario name or "all":
+1. Verify Docker is running
+2. Run the appropriate make target
+3. Capture full output (do not truncate)
+4. Parse results
+
+For a single scenario:
+```bash
+molecule test -s <scenario>
+```
+
+For all scenarios on one platform:
+```bash
+make molecule
+```
+
+For all scenarios on all platforms:
+```bash
+make molecule-all
+```
+
+## Known Issues
+
+- `ansible-lint` may warn about `command-instead-of-module` for `systemctl --user`
+  calls — this is expected (systemd module doesn't support user services) and
+  skipped in `.ansible-lint`
+- Molecule Docker driver may print "Event loop is closed" warnings on interrupt — harmless
+
+## Reporting
+
+Report:
+- **PASSED**: scenario name, platform, duration
+- **FAILED**: scenario name, platform, the failing Ansible task, error message, file:line
+- **SKIPPED**: if Docker was unavailable
+
+For failures, extract:
+- The Ansible task: `TASK [gitea-runner : task_name]` followed by `FAILED!`
+- The error detail: the `msg` field in the JSON output
+- The molecule verify step: look for `VERIFY` section
+- Platform-specific failures: note if only one OS failed
+
+Do NOT attempt to fix failures — report them with enough detail for the parent agent.
+
+## Feedback Reporting
+
+When you encounter a concrete issue with a tool, workflow, or process
+that would benefit from further investigation, create a Gitea issue
+in the `oblachno-oss/grm` repo.
+
+### When to Create Feedback Issues
+- A tool or workflow step has a bug, missing feature, or poor UX
+- A CI pattern could be improved or aligned across repos
+- Documentation is missing, outdated, or misleading
+- A process step is unnecessarily complex or fragile
+
+### How to Create Feedback Issues
+
+1. **Deduplicate first**: Use `mcp_call_tool` with server_name "gitea",
+   tool_name "list_issues", with `labels: "feedback"`, `owner: "oblachno-oss"`,
+   `repo: "grm"`. Check if an open issue already covers the same topic.
+   Do NOT create duplicates.
+
+2. **Create the issue**: Use `mcp_call_tool` with server_name "gitea",
+   tool_name "issue_write", method "create_issue", `owner: "oblachno-oss"`,
+   `repo: "grm"`:
+   - **Title**: `[feedback] <category>: <short description>`
+   - **Labels**: `feedback` + one of: `tooling`, `ci-improvement`,
+     `doc-improvement`, `workflow-improvement`
+   - **Body** must include these sections:
+     ```
+     **Context**: What task you were performing, which repo
+     **Tool/Workflow**: The specific tool or workflow step involved
+     **Issue**: What went wrong or could be improved
+     **Reproduction**: Steps to reproduce (if applicable)
+     **Affected files**: File paths and line numbers
+     **Suggested investigation**: What an agent should look into
+     **Reported by**: <subagent profile name>
+     ```
+
+3. **Report back**: Include the issue URL in your report to the parent agent.
+
+### When NOT to Create Feedback Issues
+- Transient failures (network blips, rate limits, Docker pull flakiness)
+- Issues you can fix yourself — fix them instead
+- CI run failures — those are handled by `notify_failure` automatically
+- Missing labels — `configure_repo` creates standard labels on next master push
@@ -0,0 +1,154 @@
+---
+name: workflow-validator
+description: Validates Gitea Actions workflow YAML files for the grm repo using actionlint and act_runner dry-run. Fixes syntax errors, job dependency issues, and molecule distribution matrix problems.
+model: glm-5.2
+allowed-tools:
+  - mcp_call_tool
+  - mcp_list_tools
+  - mcp_read_resource
+  - read
+  - grep
+  - glob
+  - exec
+  - edit
+permissions:
+  allow:
+    - mcp__gitea__*
+    - Exec(make workflow-lint)
+    - Exec(make workflow-dryrun)
+    - Exec(make workflow-check)
+    - Exec(make install-tools)
+    - Exec(actionlint *)
+    - Exec(act_runner *)
+    - Exec(cat *)
+    - Exec(grep *)
+    - Exec(git diff *)
+---
+
+You are a Gitea Actions workflow validator for the grm repo.
+
+## Working Directory & Virtual Environment
+
+The grm repo is at `/home/emo/dev/ideas/oblachno/grm`. Always `cd` there first.
+
+All Python tools run inside `.venv`. `make` targets handle activation
+automatically — always use `make <target>`, never raw `pytest` or `ruff`
+commands. If `.venv` doesn't exist, run `make setup` first.
+
+## Key Files
+
+- `.gitea/workflows/ci.yml` — PR pipeline (quality, detect-changes, pre-merge-check, discover-runners, molecule-tests, molecule-report, release-dry-run, pr-review, auto-merge)
+- `.gitea/workflows/post-merge.yml` — master pipeline (detect-type, validate-commit-msg, release, publish, sync-wiki, badges, vikunja, configure-repo)
+- `.gitea/actionlint.yaml` — actionlint config (registers custom `docker` runner label)
+
+## Validation Procedure
+
+### Step 1: Install tools (if not present)
+```bash
+make install-tools  # installs actionlint, act_runner to ~/.local/bin
+```
+
+### Step 2: Static lint with actionlint
+```bash
+make workflow-lint
+```
+Fix any: syntax errors, invalid expressions, unknown keys, shellcheck issues,
+undefined variables, unknown actions, job dependency issues.
+
+### Step 3: Dry-run with act_runner
+```bash
+make workflow-dryrun
+```
+Fix any: image not found, circular dependencies, step ordering issues,
+matrix expansion problems.
+
+### Step 4: Full check
+```bash
+make workflow-check
+```
+
+## GRM-Specific Workflow Concerns
+
+**Molecule test distribution:**
+The `molecule-tests` job uses a matrix `[1, 2, 3, 4, 5, 6, 7, 8, 9, 10]`
+with `max-parallel: 3`. Runners beyond the discovered count skip via
+`--skip-if-excess`. The `discover-runners` job queries the Gitea API
+for available runners.
+
+If the matrix is too small, some scenarios won't run. If too large,
+excess runners skip (no harm). The default 10 slots should be enough.
+
+**Path filtering:**
+Molecule tests only run when `ansible/` or `.ansible-lint` files change.
+The `detect-changes` job sets `ansible-changed` output. If this is false,
+molecule-tests is skipped — this is expected behavior.
+
+**auto-merge and always():**
+```yaml
+auto-merge:
+  needs: [quality, detect-changes, pre-merge-check, pr-review, molecule-tests]
+  if: >-
+    always() &&
+    github.event_name == 'pull_request' &&
+    needs.quality.result == 'success' &&
+    needs.pre-merge-check.result == 'success' &&
+    needs.pr-review.result == 'success' &&
+    (needs.molecule-tests.result == 'success' || needs.molecule-tests.result == 'skipped')
+```
+
+**Gitea Actions limitations (1.26.x):**
+- No `fromJSON()` in matrix context
+- `concurrency` blocks can cause stuck jobs
+- `GITHUB_OUTPUT` for step outputs
+
+## Report
+- **actionlint results**: pass/fail per workflow file, specific errors
+- **dry-run results**: pass/fail per workflow, job dependency issues
+- **Files changed**: if any workflow YAML was modified
+- **Verification**: re-run results after fixes
+
+Do NOT commit — report back to the parent agent.
+
+## Feedback Reporting
+
+When you encounter a concrete issue with a tool, workflow, or process
+that would benefit from further investigation, create a Gitea issue
+in the `oblachno-oss/grm` repo.
+
+### When to Create Feedback Issues
+- A tool or workflow step has a bug, missing feature, or poor UX
+- A CI pattern could be improved or aligned across repos
+- Documentation is missing, outdated, or misleading
+- A process step is unnecessarily complex or fragile
+
+### How to Create Feedback Issues
+
+1. **Deduplicate first**: Use `mcp_call_tool` with server_name "gitea",
+   tool_name "list_issues", with `labels: "feedback"`, `owner: "oblachno-oss"`,
+   `repo: "grm"`. Check if an open issue already covers the same topic.
+   Do NOT create duplicates.
+
+2. **Create the issue**: Use `mcp_call_tool` with server_name "gitea",
+   tool_name "issue_write", method "create_issue", `owner: "oblachno-oss"`,
+   `repo: "grm"`:
+   - **Title**: `[feedback] <category>: <short description>`
+   - **Labels**: `feedback` + one of: `tooling`, `ci-improvement`,
+     `doc-improvement`, `workflow-improvement`
+   - **Body** must include these sections:
+     ```
+     **Context**: What task you were performing, which repo
+     **Tool/Workflow**: The specific tool or workflow step involved
+     **Issue**: What went wrong or could be improved
+     **Reproduction**: Steps to reproduce (if applicable)
+     **Affected files**: File paths and line numbers
+     **Suggested investigation**: What an agent should look into
+     **Reported by**: <subagent profile name>
+     ```
+
+3. **Report back**: Include the issue URL in your report to the parent agent.
+
+### When NOT to Create Feedback Issues
+- Transient failures (network blips, rate limits, Docker pull flakiness)
+- Issues you can fix yourself — fix them instead
+- CI run failures — those are handled by `notify_failure` automatically
+- Missing labels — `configure_repo` creates standard labels on next master push
@@ -0,0 +1,38 @@
+# devx-workflow
+
+Quick reference for devx tools when working on this repo.
+
+## PR Workflow (use these, not raw git/tea/MCP)
+
+| Task | Command |
+|------|---------|
+| Create Vikunja task | `make create-task -- --title "..." --description "..."` |
+| Create PR | `make create-pr` |
+| Push + create PR | `make push-with-pr` |
+| 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` |
+
+## Auto-merge Behavior
+
+When the `ready-to-merge` label is added and all CI checks pass:
+1. Auto-merge validates PR title format (`GRM-N: <vikunja task title>`)
+2. If branch is behind master, auto-merge **rebases via Gitea API** automatically
+3. The rebase triggers a new CI run; the next auto-merge attempt merges
+4. No manual rebase needed unless the API rebase fails
+
+## Pre-merge Check
+
+CI runs a `pre-merge-check` job early (after quality + detect-changes)
+that validates branch format, PR title, and Vikunja task match.
+This fails fast before expensive molecule tests run.
+
+## Key Rules
+
+- Never manually merge via API — always use auto-merge with `ready-to-merge` label
+- Branch naming: `GRM-N-short-description` (N = Vikunja task ID)
+- Commit format: conventional commits (`feat:`, `fix:`, `docs:`, etc.)
+- PR title: `GRM-N: <vikunja task title>` (auto-derived by `make create-pr`)
@@ -0,0 +1,92 @@
+# testing-and-debugging
+
+Make targets for testing, debugging, and CI investigation. **Use these
+instead of raw `pytest`, `ruff`, or `molecule` commands.**
+
+## Why Make Targets
+
+Make targets encapsulate the correct venv activation, PYTHONPATH, env
+vars, and flags. Running raw commands bypasses venv activation and
+produces false failures (missing dependencies, wrong Python version).
+
+## Unit Tests
+
+| Task | Command | Notes |
+|------|---------|-------|
+| Run all unit tests | `make test-unit` | Fast, no coverage |
+| Run with coverage | `make pytest-cov` | **Required before push** — enforces 100% |
+| Run single test | `make pytest-cov TEST=tests/test_foo.py::test_bar` | |
+
+## Linting
+
+| Task | Command | Notes |
+|------|---------|-------|
+| Full lint | `make lint-all` | ruff + pyright + bandit + ansible-lint + checkmake + actionlint |
+| Ruff only | `make lint-ruff` | |
+| Type check | `make typecheck` | pyright |
+| Bandit | `make lint-bandit` | Security linter |
+| Workflow lint | `make workflow-check` | actionlint + act_runner dry-run |
+
+## Molecule Tests
+
+| Task | Command | Notes |
+|------|---------|-------|
+| All scenarios | `make molecule` | All 6 scenarios on Ubuntu 22.04 |
+| All platforms | `make molecule-all` | All 6 scenarios on all 4 OSes |
+| Parallel | `make molecule-all-parallel` | MOLECULE_JOBS=4 |
+
+## Pre-Push Verification
+
+**Before pushing any branch:**
+
+```bash
+make pre-push
+```
+
+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.
+
+## CI Failure Investigation
+
+When investigating a CI failure:
+
+1. **Fetch logs via MCP** — use `mcp_call_tool` with gitea server,
+   `actions_run_read` method, `download_job_log` tool
+2. **Reproduce locally** — use `make pytest-cov` or `make lint-ci`
+   depending on which CI job failed
+3. **Never run raw pytest** — always use the make target
+
+## Virtual Environment
+
+All commands run inside `.venv`. `make` targets handle activation
+automatically. For raw commands (rare), activate first:
+
+```bash
+source activate.sh       # bash/zsh
+source activate.fish     # fish
+source activate.zsh      # zsh
+```
+
+If `.venv` doesn't exist, run `make setup` first.
+
+## Common Pitfalls
+
+### Coverage Verification Before Push
+
+**Always run `make pytest-cov` before pushing** — CI enforces 100%
+coverage and will fail the PR if any lines are uncovered. This is the
+most common cause of CI quality job failures after code changes. The
+pre-push git hook only validates Vikunja task existence, not tests.
+
+### API Response Type Checking
+
+Never use `is True`/`is False` identity checks on API response values.
+Many APIs return boolean values as strings (`"true"`/`"false"`). Use
+string comparison or truthy/falsy helpers instead.
+
+### Time Mocking in Tests
+
+Always mock `time.sleep` and `time.monotonic` in unit tests using
+`@patch` decorators. Real sleep calls make tests slow and exceed test
+speed limits.
@@ -20,47 +20,42 @@ jobs:
        env:
          CI_GITEA_TOKEN: ${{ secrets.CI_GITEA_TOKEN }}
          CI_GITEA_USERNAME: ${{ vars.CI_GITEA_USERNAME }}
-        run: make setup-image EXTRAS=lint
+        run: make setup-image EXTRAS=ci,lint
      - name: Lint all
        run: |
-          . .venv/bin/activate
+          . .venv/bin/activate 2>/dev/null || true
          export PATH="$HOME/.local/bin:$PATH"
          make lint-all
      - name: Unit tests with 100% coverage
        run: |
-          . .venv/bin/activate
+          . .venv/bin/activate 2>/dev/null || true
          make pytest-cov
      - name: Documentation lint check
        env:
          PYTHONPATH: src
-          CI_GITEA_TOKEN: ${{ secrets.CI_GITEA_TOKEN }}
-          CI_GITEA_USERNAME: ${{ vars.CI_GITEA_USERNAME }}
        run: |
-          . .venv/bin/activate
-          pip install --upgrade devx \
-            --index-url "https://${CI_GITEA_USERNAME}:${CI_GITEA_TOKEN}@git.oblachno.oblachno.fyi/api/packages/oblachno-oss/pypi/simple/" \
-            --no-deps
+          . .venv/bin/activate 2>/dev/null || true
          python3 -m devx.ci.lint_docs --root .
      - name: Translation completeness check
        run: |
-          . .venv/bin/activate
+          . .venv/bin/activate 2>/dev/null || true
          python3 -m devx.ci.check_translations --translations src/gitea_runner_manager/translations.json
      - name: Check unit test speed
        env:
          PYTHONPATH: src
        run: |
-          . .venv/bin/activate
+          . .venv/bin/activate 2>/dev/null || true
          python3 -m devx.tools.check_test_speed --max-seconds 4 --max-single-seconds 0.5
      - name: Dependency security scan
        run: |
-          . .venv/bin/activate
+          . .venv/bin/activate 2>/dev/null || true
          # Install pip in venv if missing (needed by pip-audit)
          .venv/bin/python -m ensurepip 2>/dev/null || true
          PIPAPI_PYTHON_LOCATION=$PWD/.venv/bin/python \
            pip-audit --desc --skip-editable 2>&1 || true
      - name: Workflow dry-run validation
        run: |
-          . .venv/bin/activate
+          . .venv/bin/activate 2>/dev/null || true
          export PATH="$HOME/.local/bin:$PATH"
          # Best-effort: only runs if act_runner is installed
          if command -v act_runner >/dev/null 2>&1; then
@@ -90,7 +85,7 @@ jobs:
          DEVX_VERSION_FILE: src/gitea_runner_manager/__init__.py
          DEVX_TASK_PREFIX: GRM
        run: |
-          . .venv/bin/activate
+          . .venv/bin/activate 2>/dev/null || true
          export PATH="$HOME/.local/bin:$PATH"
          python3 -m devx.ci.release --dry-run

@@ -116,12 +111,43 @@ jobs:
          PYTHONPATH: src
          DEVX_TASK_PREFIX: GRM
        run: |
-          . .venv/bin/activate
+          . .venv/bin/activate 2>/dev/null || true
          python3 -m devx.ci.classify_changes \
            --base "origin/master" \
            --head "${{ github.event.pull_request.head.sha || github.sha }}" \
            --github-output

+  pre-merge-check:
+    needs: [quality, detect-changes]
+    if: github.event_name == 'pull_request'
+    runs-on: docker
+    container: git.oblachno.oblachno.fyi/oblachno-oss/runner-images/ci-base:latest
+    timeout-minutes: 5
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - name: Set up environment
+        run: make setup-image EXTRAS=ci
+      - name: Validate auto-merge preconditions
+        env:
+          CI_GITEA_TOKEN: ${{ secrets.CI_GITEA_TOKEN }}
+          VIKUNJA_TOKEN: ${{ secrets.VIKUNJA_TOKEN }}
+          DEVX_TASK_PREFIX: GRM
+          DEVX_VIKUNJA_PROJECT_ID: 6
+          HEAD_REF: ${{ github.head_ref }}
+          PR_TITLE: ${{ github.event.pull_request.title }}
+          REPOSITORY: ${{ github.repository }}
+          PR_NUMBER: ${{ github.event.number }}
+          PYTHONPATH: ${{ env.PYTHONPATH }}
+        run: |
+          . .venv/bin/activate 2>/dev/null || true
+          python3 -m devx.ci.check_auto_merge_ready \
+            --branch "$HEAD_REF" \
+            --pr-title "$PR_TITLE" \
+            --repo "$REPOSITORY" \
+            --pr-number "$PR_NUMBER"
+
  discover-runners:
    needs: [detect-changes]
    if: needs.detect-changes.outputs.ansible-changed == 'true'
@@ -145,7 +171,7 @@ jobs:
          MOLECULE_RUNNERS: ${{ vars.MOLECULE_RUNNERS }}
          PYTHONPATH: src
        run: |
-          . .venv/bin/activate
+          . .venv/bin/activate 2>/dev/null || true
          python3 -m devx.molecule.discover_runners \
            --owner "${{ github.repository_owner }}" \
            --repo "${{ github.event.repository.name }}" \
@@ -171,7 +197,7 @@ jobs:
        run: make setup-image EXTRAS=ci,molecule
      - name: Install Ansible collections
        run: |
-          . .venv/bin/activate
+          . .venv/bin/activate 2>/dev/null || true
          python3 -m devx.tools.setup --skip-install --no-pre-commit --no-tea-login
      - name: Discover assigned test pairs
        env:
@@ -179,7 +205,7 @@ jobs:
          MAX_RUNNERS: ${{ needs.discover-runners.outputs.runner-count }}
          PYTHONPATH: src
        run: |
-          . .venv/bin/activate
+          . .venv/bin/activate 2>/dev/null || true
          python3 -m devx.molecule.distribute_molecule \
            --runner-index "$RUNNER_INDEX" \
            --max-runners "$MAX_RUNNERS" \
@@ -187,7 +213,7 @@ jobs:
      - name: Run molecule tests
        if: env.SKIP != 'true'
        run: |
-          . .venv/bin/activate
+          . .venv/bin/activate 2>/dev/null || true
          if [ -z "$TEST_PAIRS" ]; then exit 0; fi
          if ! python3 -c "import docker; docker.from_env().ping()" 2>/dev/null; then
            echo "Docker not available in CI container — skipping molecule tests"
@@ -229,7 +255,7 @@ jobs:
          PYTHONPATH: src
        run: |
          set -euo pipefail
-          . .venv/bin/activate
+          . .venv/bin/activate 2>/dev/null || true
          python3 -m devx.ci.pr_review \
            "${{ github.event.number }}" \
            "${{ github.repository }}"
@@ -239,11 +265,12 @@ jobs:
    # from the branch name, validates the PR title, and squash-merges.
    # Uses always() so it evaluates even when molecule-tests is skipped
    # (Gitea Actions skips dependent jobs of skipped jobs by default).
-    needs: [quality, detect-changes, pr-review, molecule-tests, release-dry-run]
+    needs: [quality, detect-changes, pre-merge-check, pr-review, molecule-tests, release-dry-run]
    if: >-
      always() &&
      github.event_name == 'pull_request' &&
      needs.quality.result == 'success' &&
+      needs.pre-merge-check.result == 'success' &&
      needs.pr-review.result == 'success' &&
      (needs.molecule-tests.result == 'success' || needs.molecule-tests.result == 'skipped') &&
      (needs.release-dry-run.result == 'success' || needs.release-dry-run.result == 'skipped')
@@ -270,14 +297,14 @@ jobs:
          REPOSITORY: ${{ github.repository }}
          PYTHONPATH: src
        run: |
-          . .venv/bin/activate
+          . .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 (quality, molecule, pr-review)."
+            --body "Auto-approved: all CI checks passed (quality, molecule, pr-review, pre-merge-check)."
      - name: Squash merge with task ID
        env:
          CI_GITEA_TOKEN: ${{ secrets.CI_GITEA_TOKEN }}
@@ -290,7 +317,7 @@ jobs:
          REPOSITORY: ${{ github.repository }}
          PR_NUMBER: ${{ github.event.number }}
        run: |
-          . .venv/bin/activate
+          . .venv/bin/activate 2>/dev/null || true
          python3 -m devx.ci.auto_merge \
            "$HEAD_REF" \
            "$PR_TITLE" \
@@ -56,7 +56,7 @@ jobs:
        env:
          PYTHONPATH: src
        run: |
-          . .venv/bin/activate
+          . .venv/bin/activate 2>/dev/null || true
          python3 -m devx.ci.detect_release_commit

  validate-commit-msg:
@@ -79,7 +79,7 @@ jobs:
          PYTHONPATH: src
          DEVX_TASK_PREFIX: GRM
        run: |
-          . .venv/bin/activate
+          . .venv/bin/activate 2>/dev/null || true
          git log -1 --format=%B > commit-msg.txt
          python3 -m devx.ci.validate_commit_msg commit-msg.txt --branch master
          rm -f commit-msg.txt
@@ -114,7 +114,7 @@ jobs:
          DEVX_TASK_PREFIX: GRM
          DEVX_VIKUNJA_PROJECT_ID: 6
        run: |
-          . .venv/bin/activate
+          . .venv/bin/activate 2>/dev/null || true
          export PATH="$HOME/.local/bin:$PATH"
          python3 -m devx.ci.release
      - name: Notify on failure
@@ -152,7 +152,7 @@ jobs:
          CI_GITEA_TOKEN: ${{ secrets.CI_GITEA_TOKEN }}
          PYTHONPATH: src
        run: |
-          . .venv/bin/activate
+          . .venv/bin/activate 2>/dev/null || true
          export PATH="$HOME/.local/bin:$PATH"
          python3 -m devx.ci.publish \
            "${{ needs.release.outputs.tag }}" \
@@ -191,7 +191,7 @@ jobs:
          CI_GITEA_TOKEN: ${{ secrets.CI_GITEA_TOKEN }}
          PYTHONPATH: src
        run: |
-          . .venv/bin/activate
+          . .venv/bin/activate 2>/dev/null || true
          python3 -m devx.ci.sync_wiki --repo "${{ github.repository }}" --strict
      - name: Notify on failure
        if: failure()
@@ -231,7 +231,7 @@ jobs:
        env:
          PRE_COMMIT_ALLOW_NO_CONFIG: "1"
        run: |
-          . .venv/bin/activate
+          . .venv/bin/activate 2>/dev/null || true
          python3 -m devx.ci.push_badges
      - name: Notify on failure
        if: failure()
@@ -268,7 +268,7 @@ jobs:
          DEVX_TASK_PREFIX: GRM
          DEVX_VIKUNJA_PROJECT_ID: 6
        run: |
-          . .venv/bin/activate
+          . .venv/bin/activate 2>/dev/null || true
          python3 -m devx.ci.post_merge --git-sha "${{ github.sha }}"
      - name: Notify on failure
        if: failure()
@@ -304,7 +304,7 @@ jobs:
          DEVX_REPO_OWNER: oblachno-oss
          DEVX_STATUS_CHECKS: "CI / quality (pull_request),CI / molecule-tests (1) (pull_request),CI / molecule-tests (2) (pull_request),CI / molecule-tests (3) (pull_request)"
        run: |
-          . .venv/bin/activate
+          . .venv/bin/activate 2>/dev/null || true
          python3 -m devx.tools.configure_repo
      - name: Notify on failure
        if: failure()
@@ -57,6 +57,37 @@ repos:
        pass_filenames: false
        stages: [pre-commit]

+      - id: checkmake
+        name: checkmake Makefile linter
+        entry: make checkmake
+        language: system
+        files: ^Makefile$
+        pass_filenames: false
+        stages: [pre-commit]
+
+      - id: check-test-speed
+        name: unit test speed check
+        entry: .venv/bin/python -m devx.tools.check_test_speed --max-seconds 4 --max-single-seconds 0.5
+        language: system
+        types: [python]
+        pass_filenames: false
+        stages: [pre-commit]
+
+      - id: check-translations
+        name: translation completeness check
+        entry: env PYTHONPATH=src .venv/bin/python -m devx.ci.check_translations --translations src/gitea_runner_manager/translations.json
+        language: system
+        files: ^src/gitea_runner_manager/translations\.json$
+        pass_filenames: false
+        stages: [pre-commit]
+
+      - id: lint-docs
+        name: documentation lint check
+        entry: env PYTHONPATH=src .venv/bin/python -m devx.ci.lint_docs --root .
+        language: system
+        pass_filenames: false
+        stages: [pre-commit]
+
      - id: pytest-cov
        name: pytest with 100% coverage
        entry: make pytest-cov
@@ -1,5 +1,19 @@
 # AGENTS.md — Project Conventions for GRM

+## Virtual Environment
+
+All Python tools, tests, and scripts run inside a standard `.venv` directory.
+Activate it before running any non-`make` command:
+
+```bash
+source activate.sh       # bash/zsh
+source activate.fish     # fish
+source activate.zsh      # zsh
+```
+
+If `.venv` doesn't exist, run `make setup` first. The `make` targets handle
+venv activation automatically — always prefer `make <target>` over raw commands.
+
 ## Build & Test Commands

 ```bash
@@ -163,6 +177,12 @@ Then add the `ready-to-merge` label. The auto-merge workflow will:
 5. The post-merge workflow marks the Vikunja task as done
 6. The release workflow automatically versions, tags, and publishes (see below)

+**If the branch is behind master** (another PR merged first), auto-merge
+automatically rebases the PR's head branch via the Gitea API. This triggers
+a new CI run. The next auto-merge attempt will merge successfully.
+No manual rebase needed. To rebase manually: `make rebase` (local) or
+`make pr-rebase` (server-side via API).
+
 > **IMPORTANT**: Never manually merge PRs via the API. Always use the auto-merge
 > workflow by adding the `ready-to-merge` label. Manual merges bypass the
 > `GRM-N: <conventional>` format enforcement, producing incorrectly named commits.
@@ -171,6 +191,10 @@ Then add the `ready-to-merge` label. The auto-merge workflow will:

 ### CI Path Filtering

+The CI workflow includes a `pre-merge-check` job (runs after quality +
+detect-changes) that validates branch format, PR title, and Vikunja task
+match. This fails fast before expensive molecule tests run.
+
 The CI workflow includes a `detect-changes` job that checks whether any files
 under `ansible/` or `.ansible-lint` have changed. If no Ansible files are
 changed, molecule tests are skipped — this prevents non-Ansible changes
@@ -242,11 +266,11 @@ Not all changes require the full CI pipeline or a new release. The project
 classifies changes into two categories using `devx.ci.classify_changes`:

 **Classification strategy (safe-by-default):** Any file NOT in the explicit
-workflow-only allowlist is treated as user-facing. This prevents new file
+infrastructure allowlist is treated as user-facing. This prevents new file
 types from accidentally skipping releases. Classification is config-driven
 via `[tool.devx.classify]` in `pyproject.toml`.

-**Workflow-only paths** (infrastructure → no release needed):
+**Infrastructure paths** (no release needed):
 - `.gitea/**` — Gitea Actions workflows
 - `scripts/**` — Dev tools and CI/CD automation (not part of installed package)
 - `docs/**` — Documentation
@@ -267,7 +291,7 @@ via `[tool.devx.classify]` in `pyproject.toml`.

 **devx module structure** (installed from git, not in this repo):
 - `devx.ci.*` — CI/CD automation (run by workflows): release, publish, auto_merge, classify_changes, detect_release_commit, push_badges, doc_coverage, sync_wiki, distribute_molecule, molecule_ci_guard, discover_runners, notify_failure, post_merge, pr_review, validate_commit_msg
- `devx.tools.*` — Dev tools (run locally): check_test_speed, configure_repo, install_checkmake, install_tools, setup, generate_badges
+- `devx.tools.*` — Dev tools (run locally): check_test_speed, configure_repo, install_checkmake, install_tools, setup, generate_badges, create_task, create_pr, pr_status, pr_logs, pr_label, rebase, pr_rebase
 - `devx.molecule.*` — Molecule helpers: molecule_all, platforms, discover_runners, distribute_molecule, molecule_ci_guard
 - `devx.gitea_cli` — Tea CLI wrapper
 - `devx.i18n` — i18n translation system
@@ -283,7 +307,7 @@ via `[tool.devx.classify]` in `pyproject.toml`.

 **AI agents must follow these rules:**
 - When working on workflow/CI/docs-only changes, use `ci:` or `docs:` commit prefixes
- Do NOT bump the version or create tags for workflow-only changes
+- Do NOT bump the version or create tags for infrastructure-only changes
 - The `classify_changes` module enforces this automatically — no manual intervention needed

 ## Source Code Separation and devx Integration
@@ -397,7 +421,7 @@ The devx package is configured via `DEVX_*` environment variables:
 - `DEVX_VIKUNJA_PROJECT_ID=6` — Vikunja project ID for task tracking
 - `DEVX_VERSION_FILE=src/gitea_runner_manager/__init__.py` — Path to the version source file

-Change classification is config-driven via `[tool.devx.classify]` in `pyproject.toml`, which defines the workflow-only and user-facing path patterns.
+Change classification is config-driven via `[tool.devx.classify]` in `pyproject.toml`, which defines the infrastructure and user-facing path patterns.

 ## Key Conventions

@@ -409,6 +433,50 @@ Change classification is config-driven via `[tool.devx.classify]` in `pyproject.
 - Secrets are passed via temp JSON files, never on the command line (CWE-214)
 - CI triggers only on `opened` and `synchronize` PR events (not `labeled`)

+### Testing Conventions
+
+- **Always run `make pytest-cov` before pushing** — CI enforces 100%
+  coverage and will fail the PR if any lines are uncovered. The pre-push
+  hook only validates Vikunja task existence, not tests.
+- **Never use `is True`/`is False` identity checks on API response
+  values** — many APIs return boolean values as strings (`"true"`/
+  `"false"`). Use string comparison or truthy/falsy helpers instead.
+- **Always mock `time.sleep` and `time.monotonic` in unit tests** — real
+  sleep calls make tests slow and exceed test speed limits. Use
+  `@patch("time.sleep")` and `@patch("time.monotonic")` decorators.
+- **Extract complex inline shell from workflows to tested Python tools**
+  — SSH loops, curl polling, docker exec chains, and multi-line
+  if/then/else shell blocks should be Python scripts in `scripts/`
+  with unit tests. Simple variable checks and venv activation are fine
+  as inline shell.
+
+### Container-Level Fix Verification (Mandatory)
+
+**Rule:** Before pushing any fix that modifies container state (CA certs,
+config files, installed packages, daemon restarts), reproduce the exact
+sequence locally with the actual Docker image. Do not push to CI as the
+first test.
+
+This is a hard rule, not a suggestion. CI cycles take 20+ minutes and
+ephemeral staging VMs are destroyed after each run, making interactive
+debugging impossible. A local reproduction takes 30 seconds and catches
+silent failures immediately.
+
+**Procedure:**
+1. `docker pull <actual_image>`
+2. `docker run -d --name <test> ...` and wait for it to start
+3. Run the exact commands from the Ansible task or script
+4. Verify the state change took effect
+5. Clean up: `docker rm -f <test>`
+
+### Verified State Modification (Mandatory)
+
+Ansible tasks that modify container state with `changed_when: false`
+MUST include a post-task verification step that confirms the state
+change took effect. `changed_when: false` suppresses both change
+detection AND failure visibility — a task can silently do nothing and
+report `ok`.
+
 ## Ansible Role Structure

 ```
@@ -422,10 +490,12 @@ main.yml → systemd_check → user_setup → rootless_docker → install_runner

 ## Molecule Scenarios

-6 scenarios: `default`, `multi-instance`, `lifecycle`, `template-content`, `deregister`, `update`
+7 scenarios: `default`, `multi-instance`, `lifecycle`, `template-content`, `deregister`, `update`, `remove`
 4 platforms: `ubuntu-2204`, `ubuntu-2404`, `debian-12`, `archlinux`
 Platform list is defined in `devx.molecule.platforms` (single source of truth)

+Note: `make molecule` and `make molecule-all` run 6 scenarios (excluding `remove`, which destroys the test container). CI discovers all 7 scenarios via `devx.molecule.distribute_molecule`.
+
 ## Known Issues

 - `ansible-lint` may warn about `command-instead-of-module` for `systemctl --user` calls — this is expected (systemd module doesn't support user services) and skipped in `.ansible-lint`
@@ -475,3 +545,86 @@ docs/
 2. If adding a new page, add it to `docs/mapping.json`
 3. Commit and create a PR (standard PR workflow)
 4. On merge, wiki is automatically synced
+
+## Subagent Delegation Policy
+
+Custom subagent profiles are defined in `.devin/agents/` (project-specific)
+and `~/.config/devin/agents/` (global, shared across repos). The agent MUST
+automatically delegate to the appropriate subagent based on the task —
+the user should not need to specify which profile to use.
+
+### Available Profiles
+
+**Global** (shared with infra and devx):
+
+| Profile | Location | Purpose |
+|---------|----------|---------|
+| `pr-reviewer` | `~/.config/devin/agents/` | 13-category PR checklist + quality gates |
+| `release-check` | `~/.config/devin/agents/` | Pre-merge readiness validation |
+
+**grm-specific** (in `.devin/agents/`):
+
+| Profile | Purpose |
+|---------|---------|
+| `ci-investigator` | Investigate CI failures (quality, molecule, release, publish, wiki sync) |
+| `molecule-runner` | Run 7 molecule scenarios across 4 platforms, report pass/fail |
+| `dep-upgrader` | Python + Ansible dependency upgrades with molecule verification |
+| `doc-syncer` | Doc coverage, doc linting, wiki sync for grm docs |
+| `workflow-validator` | actionlint + act_runner dry-run for grm workflows |
+
+### When to Delegate Automatically
+
+| Trigger | Profile | Mode |
+|---------|---------|------|
+| CI run failure (quality, molecule-tests, release, publish, sync-wiki) | `ci-investigator` | Background |
+| PR ready for review | `pr-reviewer` | Foreground |
+| Molecule tests need to run | `molecule-runner` | Background |
+| Dependency upgrade requested | `dep-upgrader` | Background |
+| Doc coverage failure or wiki sync issue | `doc-syncer` | Background |
+| Workflow YAML modified or validation needed | `workflow-validator` | Background |
+| Branch ready for merge | `release-check` | Foreground |
+
+### Delegation Rules
+
+1. **Auto-select the profile.** Do not ask the user which profile to use.
+2. **Background by default, foreground when blocking.**
+3. **Provide full context in the prompt** — subagents don't inherit conversation history.
+4. **One subagent per concern.** Chain: investigate → fix in main session → review.
+5. **Don't delegate trivial work** (<30s, <50 lines of context).
+6. **Compact after subagent returns.**
+7. **Never skip delegation to save time** — it keeps main context small.
+
+
+## Feedback Issue Handling
+
+Subagents create Gitea issues in the current repo when they encounter
+tool, workflow, or process issues that warrant follow-up. These issues
+use the `feedback` label plus a category label (`tooling`,
+`ci-improvement`, `doc-improvement`, `workflow-improvement`).
+
+Standard labels are created automatically by `configure_repo` (runs in
+post-merge on every master push). If a label does not exist yet, the
+subagent's issue creation will still succeed — labels can be added
+afterwards.
+
+### When a Subagent Reports a Feedback Issue URL
+
+1. **Acknowledge it** in your response to the user — mention the issue URL
+2. **Do NOT close or modify** the issue — it is for follow-up work
+3. **Do NOT create a PR** to address it unless the user explicitly asks
+4. If the user asks to address feedback, spawn a subagent to investigate
+   the issue and implement a fix
+
+### Creating Feedback Issues Manually
+
+As the parent agent, you can also create feedback issues directly using
+the Gitea MCP (`issue_write` with `create_issue` method). Follow the
+same format as subagents:
+
+- Title: `[feedback] <category>: <short description>`
+- Labels: `feedback` + category label
+- Body: include context, tool/workflow, issue, reproduction, affected
+  files, suggested investigation, and "Reported by: parent agent"
+
+Always deduplicate first via `list_issues` with `labels: "feedback"`.
+
@@ -2,6 +2,30 @@

 All notable changes to this project will be documented in this file.

+## [0.14.2] - 2026-07-05
+
+### Bug Fixes
+
+- Add pre-commit hooks for quality gates matching CI
+
+## [0.14.1] - 2026-07-01
+
+### Refactor
+
+- Align venv management to devx.mak targets
+
+## [0.14.0] - 2026-07-01
+
+### Features
+
+- Bump devx to v0.30.0
+
+## [0.13.0] - 2026-07-01
+
+### Features
+
+- Bump devx to v0.29.1, upgrade molecule, ubuntu 26.04
+
 ## [0.12.5] - 2026-06-30

 ### Bug Fixes
@@ -1,4 +1,4 @@
-.PHONY: all setup setup-ci setup-quality setup-molecule setup-release setup-image install update lint ansible-lint makefile-lint lint-all lint-ruff lint-format lint-bandit lint-deps typecheck checkmake install-hooks test test-unit pytest-cov molecule molecule-all test-all clean workflow-lint workflow-dryrun workflow-check install-tools
+.PHONY: all setup setup-ci setup-quality setup-molecule setup-release setup-image install update lint ansible-lint makefile-lint lint-all lint-ruff lint-format lint-bandit lint-deps typecheck checkmake install-hooks test test-unit pytest-cov molecule molecule-all test-all clean workflow-lint workflow-dryrun workflow-check install-tools check-api-identity-checks
 .PHONY: configure-gitea-pypi
 .PHONY: create-task create-pr push-with-pr git-push

@@ -25,6 +25,18 @@ DEVX_LINT_PATHS := src/ scripts/ tests/
 DEVX_MAK := $(shell $(BIN)/python -c \
 	"from pathlib import Path; import devx; print(Path(devx.__file__).parent / 'make' / 'devx.mak')" \
 	2>/dev/null)
+# Fallback: when the venv doesn't exist yet, try system python3 or /opt/venv.
+# In CI, /opt/venv has devx pre-installed; locally, devx may be in system python.
+ifeq ($(strip $(DEVX_MAK)),)
+DEVX_MAK := $(shell python3 -c \
+	"from pathlib import Path; import devx; print(Path(devx.__file__).parent / 'make' / 'devx.mak')" \
+	2>/dev/null)
+endif
+ifeq ($(strip $(DEVX_MAK)),)
+DEVX_MAK := $(shell /opt/venv/bin/python -c \
+	"from pathlib import Path; import devx; print(Path(devx.__file__).parent / 'make' / 'devx.mak')" \
+	2>/dev/null)
+endif
 -include $(DEVX_MAK)

 # Full setup for local development (all deps, tools, collections, hooks)
@@ -77,28 +89,14 @@ setup-image:
 		pip install -e .$(if $(EXTRAS),[$(EXTRAS)],); \
 	else echo "[setup-image] /opt/venv not found — falling back to setup-ci"; $(MAKE) setup-ci; fi

-# Helper: run pip install with Gitea registry configured
-# Usage: $(PIP_INSTALL) install -e '.[ci,lint]'
-PIP_INSTALL := if [ -z "$$CI_GITEA_TOKEN" ]; then . ./.env 2>/dev/null; fi; \
-	CI_GITEA_TOKEN="$$CI_GITEA_TOKEN"; \
-	if [ -n "$$CI_GITEA_TOKEN" ]; then export PIP_EXTRA_INDEX_URL="https://$$CI_GITEA_USERNAME:$$CI_GITEA_TOKEN@git.oblachno.oblachno.fyi/api/packages/oblachno-oss/pypi/simple/"; fi; \
-	$(BIN)/pip
-
-$(VENV)/bin/activate:
-	@python3 -c "import sys; v=sys.version_info; assert v >= (3, 12), f'Python 3.12+ required, found {v.major}.{v.minor}'; print(f'Python {v.major}.{v.minor}.{v.micro} OK')"
-	$(PYTHON) -m venv $(VENV)
-	$(BIN)/pip install --upgrade pip setuptools wheel
-
-.env:
-	@if [ ! -f .env ]; then \
-		cp .env.example .env; \
-		echo "Created .env from .env.example — please edit it with your credentials."; \
-	fi
-
-activate-scripts: $(VENV)/bin/activate
-	@test -f activate.sh || (echo '#!/usr/bin/env bash' > activate.sh && echo 'source "$$(cd "$$(dirname "$${BASH_SOURCE[0]}")" && pwd)/.venv/bin/activate"' >> activate.sh && chmod +x activate.sh)
-	@test -f activate.fish || (echo '#!/usr/bin/env fish' > activate.fish && echo 'set -l script_dir (dirname (status --current-filename))' >> activate.fish && echo 'source "$$script_dir/.venv/bin/activate.fish"' >> activate.fish && chmod +x activate.fish)
-	@test -f activate.zsh || (echo '#!/usr/bin/env zsh' > activate.zsh && echo '0="$${ZERO:-$${0:#$$ZSH_ARGZERO}}"' >> activate.zsh && echo '0="$${$${(M)0:#/*}:-$$PWD/$$0}"' >> activate.zsh && echo 'source "$${0:A:h}/.venv/bin/activate"' >> activate.zsh && chmod +x activate.zsh)
+# venv, .env, activate-scripts, and PIP_INSTALL are provided by devx.mak
+# (devx-venv, devx-env, devx-activate-scripts, DEVX_PIP_INSTALL)
+# Aliases for convenience and backward compatibility:
+.PHONY: venv activate-scripts
+PIP_INSTALL := $(DEVX_PIP_INSTALL)
+venv: devx-venv
+.env: devx-env
+activate-scripts: devx-activate-scripts

 install:
 	@if [ -z "$(HOST)" ]; then echo "HOST is required. Example: make install HOST=192.168.1.10"; exit 1; fi
@@ -175,7 +173,10 @@ makefile-lint:
 		echo "checkmake not found, skipping Makefile lint"; \
 	fi

-lint-all: lint ansible-lint makefile-lint workflow-lint
+lint-all: lint ansible-lint makefile-lint workflow-lint check-api-identity-checks
+
+check-api-identity-checks:
+	@$(BIN)/python -m devx.tools.check_api_identity_checks

 test-integration:
 	$(BIN)/pytest tests/integration/ -v --no-cov
@@ -8,12 +8,12 @@ Each runner runs in an isolated **rootless Docker** environment under a dedicate

 [![CI](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/actions/workflows/ci.yml/badge.svg)](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/actions)
 [![License: GPL-3.0](https://img.shields.io/badge/license-GPL--3.0-blue)](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/src/branch/master/LICENSE)
-[![Coverage](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/raw/commit/ec6dc73ab2448cdf01779bfabe90f70675684a17/coverage.svg)](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/actions)
-[![Tests](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/raw/commit/ec6dc73ab2448cdf01779bfabe90f70675684a17/tests.svg)](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/actions)
-[![Docs](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/raw/commit/ec6dc73ab2448cdf01779bfabe90f70675684a17/docs.svg)](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/wiki)
-[![Code Quality](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/raw/commit/ec6dc73ab2448cdf01779bfabe90f70675684a17/quality.svg)](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/actions)
-[![Version](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/raw/commit/ec6dc73ab2448cdf01779bfabe90f70675684a17/version.svg)](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/releases)
-[![Python](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/raw/commit/ec6dc73ab2448cdf01779bfabe90f70675684a17/python.svg)](https://www.python.org/downloads/)
+[![Coverage](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/raw/commit/bdbbfb7b82a9721d5d103a1008dde317d19a82b8/coverage.svg)](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/actions)
+[![Tests](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/raw/commit/bdbbfb7b82a9721d5d103a1008dde317d19a82b8/tests.svg)](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/actions)
+[![Docs](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/raw/commit/bdbbfb7b82a9721d5d103a1008dde317d19a82b8/docs.svg)](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/wiki)
+[![Code Quality](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/raw/commit/bdbbfb7b82a9721d5d103a1008dde317d19a82b8/quality.svg)](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/actions)
+[![Version](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/raw/commit/bdbbfb7b82a9721d5d103a1008dde317d19a82b8/version.svg)](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/releases)
+[![Python](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/raw/commit/bdbbfb7b82a9721d5d103a1008dde317d19a82b8/python.svg)](https://www.python.org/downloads/)

 ## Why GRM?

@@ -151,6 +151,7 @@ GRM provides a single `grm` command with subcommands for the full runner lifecyc
 | `grm remove <name> --force` | Remove only the local registry entry (skip remote cleanup) |
 | `grm list` | List all registered runners with live status |
 | `grm list --no-status` | List registered runners without SSH status checks |
+| `grm health [name]` | Run health check (Docker, runner service, disk) on one or all runners |
 | `grm trigger-workflow <workflow_id>` | Trigger a Gitea Actions workflow via the API |
 | `grm trigger-workflow --list` | List available workflows in the repository |
 | `grm --version` | Show the installed version |
@@ -1,6 +1,6 @@
 ---
 gitea_runner_version: "1.0.8"
-runner_labels: "docker,ubuntu-latest:docker://runner-images:ubuntu-22.04"
+runner_labels: "docker,ubuntu-latest:docker://runner-images:ubuntu-26.04"
 skip_runner_registration: false

 # Per-runner user (rootless isolation)
@@ -4,7 +4,7 @@ driver:

 platforms:
  - name: ${MOLECULE_PLATFORM_NAME:-ubuntu-2204}
-    image: ${MOLECULE_PLATFORM_IMAGE:-ubuntu:22.04}
+    image: ${MOLECULE_PLATFORM_IMAGE:-ubuntu:26.04}
    command: ${MOLECULE_PLATFORM_COMMAND:-sleep infinity}
    volumes:
      - /sys/fs/cgroup:/sys/fs/cgroup:rw
@@ -4,7 +4,7 @@ driver:

 platforms:
  - name: ${MOLECULE_PLATFORM_NAME:-ubuntu-2204}
-    image: ${MOLECULE_PLATFORM_IMAGE:-ubuntu:22.04}
+    image: ${MOLECULE_PLATFORM_IMAGE:-ubuntu:26.04}
    command: ${MOLECULE_PLATFORM_COMMAND:-sleep infinity}
    volumes:
      - /sys/fs/cgroup:/sys/fs/cgroup:rw
@@ -4,7 +4,7 @@ driver:

 platforms:
  - name: ${MOLECULE_PLATFORM_NAME:-ubuntu-2204}
-    image: ${MOLECULE_PLATFORM_IMAGE:-ubuntu:22.04}
+    image: ${MOLECULE_PLATFORM_IMAGE:-ubuntu:26.04}
    command: ${MOLECULE_PLATFORM_COMMAND:-sleep infinity}
    volumes:
      - /sys/fs/cgroup:/sys/fs/cgroup:rw
@@ -4,7 +4,7 @@ driver:

 platforms:
  - name: ${MOLECULE_PLATFORM_NAME:-ubuntu-2204}
-    image: ${MOLECULE_PLATFORM_IMAGE:-ubuntu:22.04}
+    image: ${MOLECULE_PLATFORM_IMAGE:-ubuntu:26.04}
    command: ${MOLECULE_PLATFORM_COMMAND:-sleep infinity}
    volumes:
      - /sys/fs/cgroup:/sys/fs/cgroup:rw
@@ -4,7 +4,7 @@ driver:

 platforms:
  - name: ${MOLECULE_PLATFORM_NAME:-ubuntu-2204}
-    image: ${MOLECULE_PLATFORM_IMAGE:-ubuntu:22.04}
+    image: ${MOLECULE_PLATFORM_IMAGE:-ubuntu:26.04}
    command: ${MOLECULE_PLATFORM_COMMAND:-sleep infinity}
    volumes:
      - /sys/fs/cgroup:/sys/fs/cgroup:rw
@@ -4,7 +4,7 @@ driver:

 platforms:
  - name: ${MOLECULE_PLATFORM_NAME:-ubuntu-2204}
-    image: ${MOLECULE_PLATFORM_IMAGE:-ubuntu:22.04}
+    image: ${MOLECULE_PLATFORM_IMAGE:-ubuntu:26.04}
    command: ${MOLECULE_PLATFORM_COMMAND:-sleep infinity}
    volumes:
      - /sys/fs/cgroup:/sys/fs/cgroup:rw
@@ -4,7 +4,7 @@ driver:

 platforms:
  - name: ${MOLECULE_PLATFORM_NAME:-ubuntu-2204}
-    image: ${MOLECULE_PLATFORM_IMAGE:-ubuntu:22.04}
+    image: ${MOLECULE_PLATFORM_IMAGE:-ubuntu:26.04}
    command: ${MOLECULE_PLATFORM_COMMAND:-sleep infinity}
    volumes:
      - /sys/fs/cgroup:/sys/fs/cgroup:rw
@@ -8,12 +8,12 @@ Each runner runs in an isolated **rootless Docker** environment under a dedicate

 [![CI](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/actions/workflows/ci.yml/badge.svg)](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/actions)
 [![License: GPL-3.0](https://img.shields.io/badge/license-GPL--3.0-blue)](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/src/branch/master/LICENSE)
-[![Coverage](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/raw/commit/ec6dc73ab2448cdf01779bfabe90f70675684a17/coverage.svg)](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/actions)
-[![Tests](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/raw/commit/ec6dc73ab2448cdf01779bfabe90f70675684a17/tests.svg)](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/actions)
-[![Docs](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/raw/commit/ec6dc73ab2448cdf01779bfabe90f70675684a17/docs.svg)](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/wiki)
-[![Code Quality](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/raw/commit/ec6dc73ab2448cdf01779bfabe90f70675684a17/quality.svg)](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/actions)
-[![Version](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/raw/commit/ec6dc73ab2448cdf01779bfabe90f70675684a17/version.svg)](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/releases)
-[![Python](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/raw/commit/ec6dc73ab2448cdf01779bfabe90f70675684a17/python.svg)](https://www.python.org/downloads/)
+[![Coverage](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/raw/commit/bdbbfb7b82a9721d5d103a1008dde317d19a82b8/coverage.svg)](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/actions)
+[![Tests](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/raw/commit/bdbbfb7b82a9721d5d103a1008dde317d19a82b8/tests.svg)](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/actions)
+[![Docs](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/raw/commit/bdbbfb7b82a9721d5d103a1008dde317d19a82b8/docs.svg)](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/wiki)
+[![Code Quality](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/raw/commit/bdbbfb7b82a9721d5d103a1008dde317d19a82b8/quality.svg)](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/actions)
+[![Version](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/raw/commit/bdbbfb7b82a9721d5d103a1008dde317d19a82b8/version.svg)](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/releases)
+[![Python](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/raw/commit/bdbbfb7b82a9721d5d103a1008dde317d19a82b8/python.svg)](https://www.python.org/downloads/)

 ## Overview

@@ -31,13 +31,14 @@ grm install <host>
              ├── rootless_docker.yml  (rootless Docker setup under runner user)
              ├── install_runner.yml   (download binary, config, register, service)
              ├── prune.yml            (Docker prune timer)
+              ├── healthcheck.yml      (health check script + systemd timer)
              └── integration_test.yml (validate service is active)
 ```

 The Ansible role task execution order (from `AGENTS.md`):

 ```
-main.yml → systemd_check → user_setup → rootless_docker → install_runner → prune → integration_test
+main.yml → systemd_check → user_setup → rootless_docker → install_runner → prune → healthcheck → integration_test
 ```

 - `install_runner.yml` handles: download, config, validate, register, service
@@ -59,6 +60,7 @@ main.yml → systemd_check → user_setup → rootless_docker → install_runner
 | `register.yml` | Registers the runner with Gitea using the registration token |
 | `service.yml` | Creates the systemd user service file and starts/enables the service |
 | `prune.yml` | Creates a systemd user timer for daily Docker image and volume pruning |
+| `healthcheck.yml` | Installs a health check script and systemd timer that monitors Docker daemon, runner service, and disk space; restarts unhealthy services automatically |
 | `integration_test.yml` | Verifies the `.runner` file exists and the systemd service is active; optionally queries the Gitea API |
 | `deregister.yml` | Deregisters the runner from Gitea and removes the `.runner` file |
 | `update_runner.yml` | Downloads a new version of the gitea_runner binary |
@@ -71,6 +73,9 @@ main.yml → systemd_check → user_setup → rootless_docker → install_runner
 | `gitea-runner-config.yaml.j2` | Runner configuration file (labels, capacity, log level) |
 | `docker-prune.service.j2` | Systemd user service for Docker pruning (oneshot) |
 | `docker-prune.timer.j2` | Systemd user timer triggering daily Docker prune |
+| `runner-healthcheck.sh.j2` | Health check script (checks Docker, runner service, disk space; restarts if down) |
+| `runner-healthcheck.service.j2` | Systemd user service for the health check (oneshot) |
+| `runner-healthcheck.timer.j2` | Systemd user timer triggering periodic health checks |

 ## Per-Runner Isolation

@@ -139,6 +144,7 @@ flowchart TD
   - Registers the runner with Gitea
   - Creates and starts the systemd user service
   - Sets up the Docker prune timer
+   - Installs the health check script and systemd timer
   - Runs the integration test (verifies `.runner` file and service state)
 7. Ansible output is streamed to a timestamped log file at `~/.local/state/grm/logs/ansible-<timestamp>.log`
 8. On success, the runner is added to the local registry at `~/.local/share/grm/runners.json`
@@ -83,7 +83,7 @@ The platform list is defined in `devx.molecule.platforms` (single source of trut

 ### CI Test Distribution

-CI runs all 6 scenarios x 4 platforms (24 test pairs) distributed across available Gitea Actions runners.
+CI runs all 7 scenarios x 4 platforms (28 test pairs) distributed across available Gitea Actions runners.

 The `discover-runners` job runs `devx.molecule.discover_runners` which queries the Gitea API for registered runners at three levels (repo, org, instance) and generates a dynamic matrix. If the API query fails (e.g., no admin access for instance-level runners), it falls back to the `MOLECULE_RUNNERS` repo variable, then to a default of 3.

@@ -10,11 +10,14 @@ GRM provides the following CLI commands for managing Gitea Actions runners. The
 | `grm update` | `<host>` | Update the gitea_runner binary on a remote host |
 | `grm start` | `<runner_name>` | Start a registered runner |
 | `grm stop` | `<runner_name>` | Stop a registered runner |
+| `grm restart` | `<runner_name>` | Restart a runner (stop, prune Docker images, start) |
 | `grm enable` | `<runner_name>` | Enable a runner to start on boot |
 | `grm disable` | `<runner_name>` | Disable and deregister a runner |
 | `grm status` | `<runner_name>` | Check the status of a registered runner |
 | `grm remove` | `<runner_name>` | Remove a runner completely |
 | `grm list` | — | List all registered runners with live status |
+| `grm health` | `[runner_name]` | Run health check (Docker, runner service, disk) on one or all runners |
+| `grm trigger-workflow` | `<workflow_id>` | Trigger a Gitea Actions workflow via the API |
 | `grm --version` | — | Show the installed version |

 ### Common lifecycle options
@@ -139,6 +142,29 @@ grm stop <runner_name> [options]
 | `--key` | `-k` | Override SSH key from registry |
 | `--ask-become-pass/--no-ask-become-pass` | — | Prompt for sudo password (default) or skip it |

+## restart
+
+Restart a registered Gitea Runner (stop, prune Docker images, start).
+
+```bash
+grm restart <runner_name> [options]
+```
+
+**Arguments:**
+
+| Argument | Description |
+|----------|-------------|
+| `runner_name` | Name of the registered runner |
+
+**Options (common lifecycle options):**
+
+| Option | Short | Description |
+|--------|-------|-------------|
+| `--host` | — | Override host from registry |
+| `--user` | `-u` | Override user from registry |
+| `--key` | `-k` | Override SSH key from registry |
+| `--ask-become-pass/--no-ask-become-pass` | — | Prompt for sudo password (default) or skip it |
+
 ## enable

 Enable a registered Gitea Runner to start on boot.
@@ -276,6 +302,70 @@ If no runners are registered:
 No runners registered. Use 'grm install' to add one.
 ```

+## health
+
+Run a health check on one or all registered runners. Checks Docker daemon status, Gitea runner service status, and disk space usage. Unhealthy services are automatically restarted by the healthcheck script.
+
+```bash
+grm health [runner_name] [options]
+```
+
+**Arguments:**
+
+| Argument | Description |
+|----------|-------------|
+| `runner_name` | (optional) Name of the runner to check. If omitted, checks all registered runners. |
+
+**Options (common lifecycle options):**
+
+| Option | Short | Description |
+|--------|-------|-------------|
+| `--host` | — | Override host from registry |
+| `--user` | `-u` | Override user from registry |
+| `--key` | `-k` | Override SSH key from registry |
+| `--ask-become-pass/--no-ask-become-pass` | — | Prompt for sudo password (default) or skip it |
+
+**Example:**
+
+```bash
+grm health
+# Check a specific runner:
+grm health prod-runner
+```
+
+Output shows NAME, HOST, HEALTHY (yes/no), and MESSAGE columns. The command exits with code 1 if any runner is unhealthy.
+
+The health check is also run automatically via a systemd timer installed by the Ansible role. See `ansible/roles/gitea-runner/templates/runner-healthcheck.sh.j2` for the script and `runner-healthcheck.timer.j2` for the timer.
+
+## trigger-workflow
+
+Trigger a Gitea Actions workflow via the API.
+
+```bash
+grm trigger-workflow <workflow_id> [options]
+grm trigger-workflow --list
+```
+
+**Arguments:**
+
+| Argument | Description |
+|----------|-------------|
+| `workflow_id` | Workflow filename (e.g., `ci.yml`) or ID |
+
+**Options:**
+
+| Option | Description |
+|--------|-------------|
+| `--list` | List available workflows in the repository |
+| `--ref` | Branch or tag to trigger on (default: repository default branch) |
+
+**Example:**
+
+```bash
+grm trigger-workflow --list
+grm trigger-workflow ci.yml --ref master
+```
+
 ## --version

 Show the installed GRM version.
@@ -34,7 +34,7 @@ ci = [
    "build==1.5.0",
    "twine==6.2.0",
    # Reusable CI/CD and dev tools (auto-merge, pr-review, pre-push checks, etc.)
-    "devx==0.27.2",
+    "devx==0.33.1",
 ]
 # Lint and type-checking tools (quality job)
 lint = [
@@ -47,14 +47,14 @@ lint = [
 ]
 # Molecule testing (molecule-tests job)
 molecule = [
-    "molecule==26.4.0",
+    "molecule==26.6.0",
    "molecule-docker==2.1.0",
 ]
 # Full dev environment (local development, includes everything)
 dev = [
    "gitea-runner-manager[ci,lint,molecule]",
    # Reusable CI/CD and dev tools (pre-push hooks, create-task, create-pr)
-    "devx==0.27.2",
+    "devx==0.33.1",
    # Non-Python dev dependency: checkmake (Makefile linter)
    # Install via: go install github.com/checkmake/checkmake/cmd/checkmake@latest
 ]
@@ -1,3 +1,3 @@
 """Gitea Runner Manager — lean CLI for managing Gitea Actions runners."""

-__version__ = "0.12.5"
+__version__ = "0.14.2"
Author	SHA1	Message	Date
grm-ci-bot	3538eb0803	release: v0.14.2 [skip ci]	2026-07-05 15:09:04 +00:00
emil	5a93559b79	GRM-132: ci: bump devx to 0.33.0, use devx-check-api-identity-checks Post-merge / detect-type (push) Successful in 50s Details Post-merge / validate-commit-msg (push) Successful in 1m5s Details Post-merge / release (push) Successful in 1m11s Details Post-merge / vikunja (push) Successful in 1m3s Details Post-merge / badges (push) Successful in 1m17s Details Post-merge / configure-repo (push) Successful in 1m3s Details Post-merge / publish (push) Successful in 1m2s Details Post-merge / sync-wiki (push) Successful in 2m38s Details	2026-07-05 15:07:03 +00:00
gitea-actions-bot	e30acbe213	chore: update badge URLs to commit bdbbfb7b [skip ci]	2026-07-02 17:01:50 +00:00
emil	386f3a88c6	GRM-131: ci: remove redundant devx reinstall in doc lint step Post-merge / detect-type (push) Successful in 1m3s Details Post-merge / publish (push) Has been skipped Details Post-merge / release (push) Successful in 57s Details Post-merge / validate-commit-msg (push) Successful in 1m5s Details Post-merge / sync-wiki (push) Successful in 2m42s Details Post-merge / vikunja (push) Successful in 1m3s Details Post-merge / configure-repo (push) Successful in 1m1s Details Post-merge / badges (push) Successful in 1m13s Details	2026-07-02 16:58:01 +00:00
gitea-actions-bot	e99e9d0ac8	chore: update badge URLs to commit 7e626586 [skip ci]	2026-07-01 23:40:46 +00:00
emil	ca1d8e5cc0	GRM-130: fix: add pre-commit hooks for quality gates matching CI Post-merge / detect-type (push) Successful in 1m8s Details Post-merge / release (push) Successful in 1m15s Details Post-merge / vikunja (push) Successful in 1m38s Details Post-merge / validate-commit-msg (push) Successful in 1m44s Details Post-merge / publish (push) Has been skipped Details Post-merge / badges (push) Successful in 1m49s Details Post-merge / sync-wiki (push) Successful in 2m28s Details Post-merge / configure-repo (push) Successful in 1m21s Details	2026-07-01 23:37:28 +00:00
gitea-actions-bot	83e800c900	chore: update badge URLs to commit b0888676 [skip ci]	2026-07-01 23:14:33 +00:00
grm-ci-bot	be17dc278c	release: v0.14.1 [skip ci]	2026-07-01 23:14:00 +00:00
emil	58b8d5b5de	GRM-130: chore: bump devx to 0.32.0, add devx.mak include fallback Post-merge / detect-type (push) Successful in 1m12s Details Post-merge / release (push) Successful in 1m4s Details Post-merge / validate-commit-msg (push) Successful in 1m8s Details Post-merge / badges (push) Successful in 1m27s Details Post-merge / publish (push) Successful in 1m8s Details Post-merge / sync-wiki (push) Successful in 2m38s Details Post-merge / vikunja (push) Successful in 1m44s Details Post-merge / configure-repo (push) Successful in 1m42s Details	2026-07-01 23:11:49 +00:00
gitea-actions-bot	48f23b554f	chore: update badge URLs to commit 627be1f1 [skip ci]	2026-07-01 22:25:36 +00:00
emil	d32bb40cbd	GRM-130: refactor: align venv management to devx.mak targets Post-merge / detect-type (push) Successful in 53s Details Post-merge / release (push) Successful in 59s Details Post-merge / publish (push) Has been skipped Details Post-merge / validate-commit-msg (push) Successful in 1m32s Details Post-merge / configure-repo (push) Successful in 1m34s Details Post-merge / vikunja (push) Successful in 1m38s Details Post-merge / badges (push) Successful in 1m46s Details Post-merge / sync-wiki (push) Successful in 2m34s Details	2026-07-01 22:22:50 +00:00
gitea-actions-bot	34954aa396	chore: update badge URLs to commit 93c752fe [skip ci]	2026-07-01 20:57:47 +00:00
emil	b9d728334f	GRM-129: docs: add container-level fix verification and verified state modification rules Post-merge / detect-type (push) Successful in 49s Details Post-merge / release (push) Successful in 1m3s Details Post-merge / publish (push) Has been skipped Details Post-merge / validate-commit-msg (push) Successful in 1m9s Details Post-merge / vikunja (push) Successful in 1m7s Details Post-merge / badges (push) Successful in 1m17s Details Post-merge / configure-repo (push) Successful in 56s Details Post-merge / sync-wiki (push) Successful in 2m8s Details	2026-07-01 20:55:35 +00:00
gitea-actions-bot	02d7c02a19	chore: update badge URLs to commit 95cb0d84 [skip ci]	2026-07-01 14:20:51 +00:00
grm-ci-bot	f861d14f32	release: v0.14.0 [skip ci]	2026-07-01 14:20:20 +00:00
emil	4359dbdc26	GRM-128: feat: bump devx to v0.30.0 Post-merge / detect-type (push) Successful in 53s Details Post-merge / release (push) Successful in 1m9s Details Post-merge / validate-commit-msg (push) Successful in 1m13s Details Post-merge / badges (push) Successful in 1m32s Details Post-merge / publish (push) Successful in 1m15s Details Post-merge / vikunja (push) Successful in 1m22s Details Post-merge / configure-repo (push) Successful in 1m25s Details Post-merge / sync-wiki (push) Successful in 2m47s Details	2026-07-01 14:18:24 +00:00
gitea-actions-bot	fc494f5cc0	chore: update badge URLs to commit 647c885c [skip ci]	2026-07-01 10:32:00 +00:00
grm-ci-bot	461ec207ad	release: v0.13.0 [skip ci]	2026-07-01 10:30:21 +00:00
emil	dca82753b2	GRM-127: feat: bump devx to v0.29.1, upgrade molecule, ubuntu 26.04 Post-merge / detect-type (push) Successful in 53s Details Post-merge / release (push) Successful in 1m30s Details Post-merge / validate-commit-msg (push) Successful in 1m48s Details Post-merge / vikunja (push) Successful in 2m1s Details Post-merge / configure-repo (push) Successful in 1m18s Details Post-merge / publish (push) Successful in 1m21s Details Post-merge / badges (push) Successful in 3m4s Details Post-merge / sync-wiki (push) Successful in 3m34s Details	2026-07-01 10:27:58 +00:00
gitea-actions-bot	3b952b09b5	chore: update badge URLs to commit b8aa4072 [skip ci]	2026-07-01 01:07:14 +00:00
emil	833792d0ad	GRM-125: ci: bump devx to v0.28.0, add pre-merge-check, agent docs Post-merge / detect-type (push) Successful in 55s Details Post-merge / release (push) Successful in 1m16s Details Post-merge / validate-commit-msg (push) Successful in 1m18s Details Post-merge / publish (push) Has been skipped Details Post-merge / badges (push) Successful in 1m31s Details Post-merge / vikunja (push) Successful in 1m20s Details Post-merge / configure-repo (push) Successful in 1m18s Details Post-merge / sync-wiki (push) Successful in 2m13s Details	2026-07-01 01:04:26 +00:00
gitea-actions-bot	d8a90eaea1	chore: update badge URLs to commit 6a2a9bb9 [skip ci]	2026-07-01 00:21:16 +00:00
emil	358620401d	GRM-124: docs: fix outdated references and document health/restart/trigger-workflow commands Post-merge / detect-type (push) Successful in 53s Details Post-merge / release (push) Successful in 59s Details Post-merge / validate-commit-msg (push) Successful in 1m20s Details Post-merge / publish (push) Has been skipped Details Post-merge / badges (push) Successful in 1m43s Details Post-merge / sync-wiki (push) Successful in 2m5s Details Post-merge / vikunja (push) Successful in 1m9s Details Post-merge / configure-repo (push) Successful in 1m8s Details	2026-07-01 00:18:44 +00:00
gitea-actions-bot	32f0ad5cb3	chore: update badge URLs to commit 2db35931 [skip ci]	2026-06-30 23:31:22 +00:00