---
title: "Quality controls and reference tooling"
description: "Required quality controls, reference tools, and when each blocks a merge."
url: "https://architecture.mnppi.org/delivery/quality-controls-and-tooling/"
status: "Current"
last_updated: "2026-07-24"
---

# Quality controls and reference tooling

**Standard details**

- Status: Current
- Reviewed: July 24, 2026
- Cadence: Review each quarter
- Source: MNPPI Org Quality Standard

One stable merge result. Each repository runs the quality controls that fit
its technology and risk.

The control defines the required result.
The listed software is the approved reference implementation.
An equivalent tool must provide the same signal and merge behavior.

When you open a PR on a Worker app, the aggregate check should fail if format,
types, tests, or `cf:check` fail. Subcheck names may change. The one
ruleset-required name should not.

> **Note — Stable contract**
>
> GitHub rulesets require a stable aggregate result.
> Tools and subchecks can change without changing that merge contract.

## Quality control matrix

Use this matrix before the first production release.
“Profile” means the control is required when the repository matches that profile.

| Control                       | Reference tooling                                                          | Applies when                                                     | Merge effect |
| ----------------------------- | -------------------------------------------------------------------------- | ---------------------------------------------------------------- | ------------ |
| Quality baseline              | `@mnppi/quality` for private repositories; token-free public workflow      | The repository contains software or dependency manifests.        | Required     |
| Format and lint               | Prettier and ESLint; Black and Flake8 for Python                           | The repository contains supported source or configuration files. | Profile      |
| Type safety                   | TypeScript or mypy                                                         | The project uses a typed language profile.                       | Profile      |
| Unused code and dependencies  | Knip                                                                       | The repository contains Node.js or TypeScript code.              | Profile      |
| Tests and coverage            | Repository test runner; pytest and pytest-cov for Python                   | The project contains behavior that can regress.                  | Profile      |
| Accessibility                 | Playwright, axe-core, and Lighthouse                                       | The project has a browser-facing interface.                      | Profile      |
| Workflow security             | actionlint and zizmor                                                      | The repository contains GitHub Actions workflows.                | Required     |
| Secrets and vulnerabilities   | Gitleaks and OSV-Scanner                                                   | A pull request changes source, dependencies, or workflow files.  | Selective    |
| Security evidence             | Semgrep, software bill of materials, dependency review, and license policy | The project risk needs additional evidence.                      | Advisory     |
| Cloudflare package validation | Production build and Wrangler dry-run                                      | Cloudflare will build or deploy the project.                     | Profile      |
| Dependency maintenance        | Renovate                                                                   | The project has managed dependencies.                            | Required     |
| Human-facing text             | MNPPI plain-language check and human review                                | A change adds or updates documentation or interface text.        | Required     |
| Shell quality                 | ShellCheck and shfmt                                                       | Shell scripts perform build, deployment, or recovery work.       | Profile      |

## Merge-effect levels

### Required

A failure blocks the aggregate merge result.
The repository cannot merge until the failure is fixed or an approved exception applies.

### Profile

The control is required when the repository matches the stated technology or application profile.
Do not run it as an empty or false-positive check.

### Selective

Only findings at the current blocking threshold stop a merge.
Other findings stay visible for review.

### Advisory

The control produces evidence and does not block by default.
Governance can promote it after a successful pilot.

## Reference profiles

### TypeScript and Node.js

Use Prettier for format and ESLint for source rules.
Run the TypeScript compiler without emit.
Use Knip for unused code, files, and dependencies.

Run the project test, coverage, package, and production build checks that apply.
Keep all required results under the repository aggregate check.

### Python

Use a frozen `uv.lock` install with the development extra.
Run Black, Flake8, mypy, Bandit, pytest, and pytest-cov.

Test supported Python versions when the package claims them.
Keep coverage expectations in the repository.

### Browser interface

Use Playwright on representative routes and interactions.
Run axe-core with the MNPPI Accessibility Conformity options.
Require zero automated axe violations.

Run Lighthouse with an accessibility score of at least 0.95.
Complete manual WCAG review before a major public release.

### Cloudflare

Build the real deployable output in GitHub before merge.
Run `wrangler deploy --dry-run` through the repository `cf:check` command.

Validate migrations, bindings, routes, and package limits when they apply.
Workers Builds still creates the authoritative production build.

## Tool selection rules

- Start with required controls, then pick the smallest suitable toolset.
- Pin exact software versions in reviewed lockfiles and machine-readable policy.
- Pin GitHub Actions and reusable workflows to full commit SHAs.
- Do not make an advisory tool mandatory without a pilot that proves value.
- Record an equivalent implementation through the [exception process](https://architecture.mnppi.org/governance/exceptions/index.md).
- Keep the [CI/CD authority boundary](https://architecture.mnppi.org/delivery/ci-cd-and-merge-controls/index.md) unchanged.

> **Caution — Version source**
>
> Do not copy a dated software snapshot into permanent policy.
> Renovate, lockfiles, and the reference application keep approved versions current.

## Primary software references

- **Code quality:** [Prettier](https://prettier.io/docs/), [ESLint](https://eslint.org/docs/latest/), [TypeScript](https://www.typescriptlang.org/docs/), and [Knip](https://knip.dev/).
- **Browser quality:** [Playwright](https://playwright.dev/docs/intro), [axe-core](https://github.com/dequelabs/axe-core), and [Lighthouse](https://developer.chrome.com/docs/lighthouse/).
- **Workflow quality:** [actionlint](https://github.com/rhysd/actionlint), [zizmor](https://docs.zizmor.sh/), [ShellCheck](https://www.shellcheck.net/), and [shfmt](https://github.com/mvdan/sh).
- **Security:** [Gitleaks](https://gitleaks.io/), [OSV-Scanner](https://google.github.io/osv-scanner/), and [Semgrep](https://semgrep.dev/docs/).
- **Python quality:** [Black](https://black.readthedocs.io/en/stable/), [Flake8](https://flake8.pycqa.org/en/latest/), [mypy](https://mypy.readthedocs.io/en/stable/), [Bandit](https://bandit.readthedocs.io/en/latest/), and [pytest](https://docs.pytest.org/en/stable/).
- **Delivery:** [Wrangler](https://developers.cloudflare.com/workers/wrangler/) and [Renovate](https://docs.renovatebot.com/).

## Acceptance gate

A repository is ready when:

- Every applicable required or profile control runs on pull requests.
- Required findings stop the stable aggregate check.
- Advisory findings stay visible and have an owner.
- The lockfile and workflow pins reproduce the reviewed toolchain.
- Any approved equivalent or temporary exception is recorded.