Defines and accepts the contract of the shared quality-check workflow (MIL-003 task 2, issue #16). Documents only; the workflow itself is task 3 (#17).
Use case first
The task row says it needs one, because running checks is something an engineer does.
UC-005 (brief): Run Project Quality Checks, primary actor Software Engineer (S02).
UCD-001: the actor Software Engineer and the use case added.
US-001: US-001.09 (same checks on every change) and US-001.10 (a failure says what to fix), with Given/When/Then criteria.
The contract (ADR-0005)
One reusable quality-checks.yml with inputs languages (a comma list of python and shell, default both), working-directory (default .) and one version input per tool.
It installs the tools from PyPI into a virtual environment: ruff 0.6.9, mypy 1.11.2, shellcheck-py 0.10.0.1, shfmt-py 3.11.0.2.
A run passes when every selected tool exits 0 and fails when any exits non-zero; a language with no files is skipped with a notice and counts as a pass.
Python: ruff check, ruff format --check, mypy --strict. Shell: shellcheck and shfmt -d on tracked *.sh. Projects configure the tools in the standard files; the workflow changes no file.
Four options were weighed: one workflow with a languages input, one workflow per language, detect from files with no inputs, and consumer-supplied commands.
Measured on the runner (2026-10-10, throwaway branch, deleted)
Ubuntu 24.04, Python 3.12, git, Node, jq, make, running as root; none of ruff, mypy, pytest, shellcheck or shfmt is preinstalled; PyPI is reachable and all four install pinned in a venv; each tool exits 1 on a finding and prints path:line and a message; shellcheck exits 1 on an empty file, so a language with no files is skipped first.
Review (S01 standing in as ADR-0002 records; no independent reader)
RC-035 UCD-001: 8 of 8 Pass. RC-036 US-001: 7 of 7 Pass. RC-037 UC-005 (Brief): all applicable pass; one finding fixed (the paragraph described the failure output). RC-038 ADR-0005: 10 Pass, 1 N-A; one finding fixed (the security impact of installing from PyPI was not named).
Action item (S05, 2026-11-28): decide on hash-pinning the tool packages before consumers outside this organization rely on it.
TM-001 lists UC-005, ADR-0005 and RC-035 to RC-038; registry next RC 039.
Not in the first version
Running the project's tests (pytest needs the project's dependencies), auto-fixing, other languages, caching of the tool install.
Defines and accepts the contract of the shared quality-check workflow (MIL-003 task 2, issue #16). Documents only; the workflow itself is task 3 (#17).
## Use case first
The task row says it needs one, because running checks is something an engineer does.
- **UC-005** (brief): Run Project Quality Checks, primary actor Software Engineer (S02).
- **UCD-001**: the actor Software Engineer and the use case added.
- **US-001**: US-001.09 (same checks on every change) and US-001.10 (a failure says what to fix), with Given/When/Then criteria.
## The contract (ADR-0005)
- One reusable `quality-checks.yml` with inputs `languages` (a comma list of `python` and `shell`, default both), `working-directory` (default `.`) and one version input per tool.
- It installs the tools from PyPI into a virtual environment: `ruff` 0.6.9, `mypy` 1.11.2, `shellcheck-py` 0.10.0.1, `shfmt-py` 3.11.0.2.
- A run passes when every selected tool exits 0 and fails when any exits non-zero; a language with no files is skipped with a notice and counts as a pass.
- Python: `ruff check`, `ruff format --check`, `mypy --strict`. Shell: `shellcheck` and `shfmt -d` on tracked `*.sh`. Projects configure the tools in the standard files; the workflow changes no file.
- Four options were weighed: one workflow with a `languages` input, one workflow per language, detect from files with no inputs, and consumer-supplied commands.
## Measured on the runner (2026-10-10, throwaway branch, deleted)
Ubuntu 24.04, Python 3.12, git, Node, jq, make, running as root; **none** of ruff, mypy, pytest, shellcheck or shfmt is preinstalled; PyPI is reachable and all four install pinned in a venv; each tool exits 1 on a finding and prints `path:line` and a message; `shellcheck` exits 1 on an empty file, so a language with no files is skipped first.
## Review (S01 standing in as ADR-0002 records; no independent reader)
- RC-035 UCD-001: 8 of 8 Pass. RC-036 US-001: 7 of 7 Pass. RC-037 UC-005 (Brief): all applicable pass; one finding fixed (the paragraph described the failure output). RC-038 ADR-0005: 10 Pass, 1 N-A; one finding fixed (the security impact of installing from PyPI was not named).
- Action item (S05, 2026-11-28): decide on hash-pinning the tool packages before consumers outside this organization rely on it.
- TM-001 lists UC-005, ADR-0005 and RC-035 to RC-038; registry next RC 039.
## Not in the first version
Running the project's tests (`pytest` needs the project's dependencies), auto-fixing, other languages, caching of the tool install.
Closes #16
Add the brief use case UC-005 (Run Project Quality Checks), the actor and
use case in UCD-001, stories US-001.09 and US-001.10, and ADR-0005 with the
inputs, the pinned tools and what a pass and a fail mean, based on a probe
of the runner image. Review and accept them (RC-035 to RC-038) and update
TM-001 and the registry.
Task: MIL-003#2
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
Defines and accepts the contract of the shared quality-check workflow (MIL-003 task 2, issue #16). Documents only; the workflow itself is task 3 (#17).
Use case first
The task row says it needs one, because running checks is something an engineer does.
The contract (ADR-0005)
quality-checks.ymlwith inputslanguages(a comma list ofpythonandshell, default both),working-directory(default.) and one version input per tool.ruff0.6.9,mypy1.11.2,shellcheck-py0.10.0.1,shfmt-py3.11.0.2.ruff check,ruff format --check,mypy --strict. Shell:shellcheckandshfmt -don tracked*.sh. Projects configure the tools in the standard files; the workflow changes no file.languagesinput, one workflow per language, detect from files with no inputs, and consumer-supplied commands.Measured on the runner (2026-10-10, throwaway branch, deleted)
Ubuntu 24.04, Python 3.12, git, Node, jq, make, running as root; none of ruff, mypy, pytest, shellcheck or shfmt is preinstalled; PyPI is reachable and all four install pinned in a venv; each tool exits 1 on a finding and prints
path:lineand a message;shellcheckexits 1 on an empty file, so a language with no files is skipped first.Review (S01 standing in as ADR-0002 records; no independent reader)
Not in the first version
Running the project's tests (
pytestneeds the project's dependencies), auto-fixing, other languages, caching of the tool install.Closes #16