DEVX-157: docs: add ADR-0003 and update docs for composite actions

docs/tech/architecture.md

@@ -453,6 +453,24 @@ v2 failures. Supports loading custom platforms from a JSON file.
 - **Secrets via environment** — secrets are passed via environment variables,
   never on the command line.
 
+## Composite Actions (`.gitea/actions/`)
+
+Reusable Gitea composite actions eliminate repeated multi-step sequences
+across workflows. Each action lives in `.gitea/actions/<name>/action.yml`
+and is referenced via `uses: ./.gitea/actions/<name>`.
+
+| Action | Purpose |
+|--------|---------|
+| `setup-env` | Run `make setup-image` (with optional `EXTRAS=`) |
+| `notify-failure` | Create a Gitea issue on job failure via `devx.ci.notify_failure` |
+| `quality-checks` | 6-step quality sequence: lint, tests, speed, docs, translations, security |
+
+Each consumer repo (`devx`, `grm`, `infra`) gets its own copy — there are
+no cross-repo composite action references. This avoids a single-point-of-failure
+where a bad devx master commit would break all repos' CI simultaneously.
+
+See ADR-0003 for the full design rationale and Gitea 1.27 constraints.
+
 ## Import rules
 
 1. **`src/devx/` is self-contained** — the package never imports from outside `src/`

docs/tech/ci-cd-workflow.md

@@ -38,22 +38,33 @@ The single validation job. Consolidates the former `quality`,
 `detect-changes`, `release-dry-run`, `pr-review`, and `pre-merge-check`
 jobs into one job to save checkout+setup overhead. Runs on every PR.
 
-**Quality steps**
+**Setup and quality steps** (composite actions)
 
-The main quality gate:
+The validate job uses three composite actions from `.gitea/actions/`:
 
-1. **Lint all** — ruff check, ruff format check, pyright, bandit, actionlint
-   (via `make lint-all`)
-2. **Unit tests with 100% coverage** — `make pytest-cov`
-3. **Check unit test speed** — `python -m devx.tools.check_test_speed
-   --max-seconds 4 --max-single-seconds 0.5`
-4. **Documentation coverage check** — `python -m devx.ci.doc_coverage
-   --fail-on-missing`
-5. **Translation completeness check** — `python -m devx.ci.check_translations`
-6. **Dependency security scan** — `pip-audit --desc --skip-editable`
-   (best-effort, non-blocking)
-7. **Workflow dry-run validation** — `make workflow-dryrun` via act_runner
-   (best-effort, skipped if act_runner is not installed)
+1. **`setup-env`** — runs `make setup-image` to link the pre-built venv
+   and install the project (no-deps mode)
+2. **`quality-checks`** — runs the 6-step quality gate:
+   - **Lint all** — ruff check, ruff format check, pyright, bandit,
+     actionlint (via `make lint-all`)
+   - **Unit tests with 100% coverage** — `make pytest-cov`
+   - **Check unit test speed** — `python -m devx.tools.check_test_speed
+     --max-seconds 15 --max-single-seconds 0.5`
+   - **Documentation gate** — `make devx-docs-check` (coverage + stale
+     refs + lint + version refs + prose)
+   - **Translation completeness check** — `python -m devx.ci.check_translations`
+   - **Dependency security scan** — `pip-audit --desc --skip-editable`
+     (best-effort, non-blocking)
+3. **`notify-failure`** — creates a Gitea issue if any step fails
+
+The quality-checks action accepts inputs (`package`, `test-speed-max`,
+`test-speed-max-single`, `translations-file`) for cross-repo reuse.
+See ADR-0003 for the composite action design rationale.
+
+**Workflow dry-run validation** (inline step, not part of composite action)
+
+`make workflow-dryrun` via act_runner (best-effort, skipped if
+act_runner is not installed).
 
 **`detect-changes` step**
 
@@ -574,8 +585,9 @@ picks up the new version number). This prevents infinite loops.
 
 ## Failure handling
 
-Every job in the CI and post-merge workflows has a `notify_failure` step
-that runs `if: failure()`. This creates a Gitea issue with the workflow name,
-run ID, and commit SHA, ensuring failures that would otherwise go unnoticed
-in the Actions tab are surfaced as issues. The issue is created via the tea
-CLI with a `bug` label if available.
+Every job in the CI, post-merge, and build-images workflows uses the
+`notify-failure` composite action (`.gitea/actions/notify-failure`),
+which runs `if: failure()`. This creates a Gitea issue with the workflow
+name, run ID, and commit SHA, ensuring failures that would otherwise go
+unnoticed in the Actions tab are surfaced as issues. The issue is created
+via the tea CLI with a `bug` label if available.