A programme · shift-left quality for the information upstream of code

Legible.

Everything that comes before code, from requirements and processes to models, decisions and contracts, made query-able for humans and AI, and checked before it is handed to a developer or a dev-agent.

Maintained by fdurieux. The page is a map: it names the artefacts, the tools and practices that already gate them, the projects started to fill the gaps, and the gaps that stay open. Where a claim is backed by a measurement it says so; where it is a mechanism we expect to work, it says that too.

Why this, and why now

Code has had quality gates for twenty years: a linter runs on every change, a severity threshold fails the build, and a baseline lets an old codebase adopt the rule without a clean-up project. The information that code is built from has had none of that. Requirements sit in documents, processes in a modelling tool, architecture in slides, decisions in people's heads. Each is checked by whoever chooses to read it.

Two things changed. First, code is now generated from that information by AI agents at near-zero cost, so its defects reach production faster and in volume. Second, the quality of what the agent is given turns out to decide the quality of what it produces. On one controlled instrument, where the diagram was the only input the generator had, code generated from sequence diagrams degrades sharply below a measurable maturity level and improves with it above that level measured. Given contracts and examples beside the diagrams, the same diagrams fixed the layout and the interfaces of the code and changed none of its behaviour measured. On the industry's reference benchmark, a large share of real issue descriptions had to be hand-graded as under-specified because no machine check exists for them research. Repairing the input measurably raises the pass rate of the generated code research.

So the foundation of a semantic transformation, where an organisation's intent becomes something a person or an agent can query rather than re-read, is also a quality problem. Information that is not well-formed cannot be queried reliably, and information that has not been checked should not be handed on. This programme treats the two halves as one.

Legible

Query-able by humans and AI. Concretely: one identity per entity across every artefact that names it, stable identifiers that other artefacts can reference, machine-readable forms beside the human ones, and traceability that can be walked in both directions, from a requirement to the model that realises it and the test that proves it.

Checked

Gated before hand-off. A deterministic check runs on every change, at the author's desk first and in the pipeline second. Findings carry a severity, a threshold fails the build, a baseline lets a brownfield estate adopt the gate without a big-bang clean-up, and a graded score shows progress rather than a yes or no.

Where it sits in the delivery pipeline

The map uses the four aspects and sixteen activities of the SAFe® Continuous Delivery Pipeline, as nomenclature only; no endorsement is implied. Each activity produces an artefact. The colour says whether that artefact is gated today, by a tool or by a practice, whether a project here is planned to gate it, or whether the gap is open. Most of Continuous Deployment carries no claim: this programme is about what happens before code, and a map coloured green all the way round would be marketing.

covered by a tool covered by a practice project planned here open gap

Continuous Exploration

Where intent is formed. The programme's home.

HypothesizeBusiness hypotheses. A pre-registered experiment is the check; no linter applies.
Collaborate & ResearchResearch notes, personas. No oracle for "did we understand the users".
ArchitectModels, decisions, contracts. Gated for PlantUML, C4, OpenAPI; open for ArchiMate, SysML, EPC, ADRs.
SynthesizeRequirements and stories. Structure is gated; wording and ambiguity are not.

Continuous Integration

Where the checks run.

DevelopCode, tests. Linters, pre-commit hooks, editor diagnostics.
BuildPipeline gates. Exit codes, thresholds, baselines; the pattern itself.
Test End-to-EndScenarios. BDD is covered; tests generated from the design are planned.
StageEnvironments. Infrastructure-as-code linters.

Continuous Deployment

Mostly no claim.

DeployNo claim.
VerifyNo claim.
MonitorNo claim.
RespondResponders inherit models kept current upstream, if they consult them at all.

Release on Demand

Governance and learning.

ReleaseAudit evidence: a gated, ratcheted model set is evidence that design documentation is current.
StabilizeProblem-solving over trustworthy models.
MeasureMaturity trends exist; checking a process design against event logs is planned.
LearnGap reports as improvement backlog.

Shift-left is a split, not a point: the artefacts are written in Continuous Exploration, the gates on them execute in Continuous Integration, at the author's desk and in the build. The per-activity reasoning, claim by claim, is in pumllint in the SDLC and the landscape it sits in is in Where tooling pays.

The gate contract

Every tool in this programme, and every third-party tool the map calls "covered", is measured against the same six properties. They are what separates a check that changes behaviour from a report that ages in a shared folder. Projects that lacked them are why the research tools of the last fifteen years are dormant: single author, grant lifetime, an IDE plug-in, no exit code.

  1. Exit codes 0, 1, 2. Clean, findings at or above the threshold, could not run. A pipeline needs nothing else to stop.
  2. A severity ladder and a threshold. Findings carry blocker, critical, major, minor or info; one flag sets where the build fails.
  3. A baseline and a ratchet. Record today's state once, fail only on regression, never update the baseline from inside the gate.
  4. A machine-readable report. JSON pinned by a published schema, and SARIF so findings appear in the code host without a plugin.
  5. Runs anywhere. No runtime dependencies, a pre-commit hook, an editor integration, and a CI action.
  6. Evidence tagging. Every claim a project makes about its value is marked measured, mechanism or hypothesis, and the measurement is published, failures included.

Artefact by artefact: tools, practices, gaps

One row per kind of upstream information. The state says how the artefact is gated today. "Threshold" and "baseline" are the contract's second and third properties; most tools outside API contracts lack them.

ArtefactStateTool or practiceThresholdBaseline or scoreWhat is missing
PlantUML modelscoveredpumllint: rules, maturity score, ratchet, traceability, editor server, CI actionyesscore and ratchetDiagram-versus-code drift (open). The best-evidenced gap in this table: one maintained model set scored 100/100 and carried 25 claims its code contradicts measured.
ARIS process models (EPC)coveredaris2puml converts to PlantUML, defects preserved, then pumllint gates. The only CI gate found for EPC.via pumllintvia pumllintA gate inside ARIS itself needs its report script validated by an adopter.
Textual requirementsplannedStrictDoc, Doorstop, Sphinx-Needs, OpenFastTrace gate structure and linksno, pass/failnoneWording rules (INCOSE, EARS) exist only in commercial tools that cannot gate CI. A deterministic wording linter is planned; ambiguity detection stays advisory.
User storiesopenNone maintainedNo machine check for an under-specified story exists.
Specification prosecoveredVale, markdownlintyesnoneVagueness in guards and conditions is not caught by prose linters.
Acceptance scenarios (Gherkin)coveredgplintpartialnone
BPMN process modelsplannedbpmnlint and the Camunda pluginserrors vs warnings onlynoneSingle-model only. Cross-model checks, pragmatic guidelines and a score are planned as a plugin.
Decision tables (DMN)covereddmnlint, small rule setnonone
Cross-artefact consistencyplannedpumllint trace links requirements, decisions and diagrams and fails on unknown referencesyesnoneExtending the identifier graph to tests and API operations is the first new project.
Architecture decisions (ADR)openadr-guard and adrpy-ai, both pre-1.0yesnoneThe established ADR tools create files and validate nothing.
C4 architecture modelscoveredStructurizr CLI validate and inspectionsyesnone
ArchiMate enterprise modelsopenArchi's validator gives hints in the GUI; scripting can encode rules but has no CI pathnononeNo shared rule catalogue; a dozen small 2025 and 2026 attempts, none gate-capable.
SysML v2 and CapellaopenPilot implementation and Capella validation rulespartialcommercial onlyNo standalone CLI gate; the only quality-gate product is commercial.
API contracts (OpenAPI, AsyncAPI)coveredSpectral, vacuum, Redoclyyesvacuum has a score and minimumThe reference pattern for a neighbouring artefact.
Schemas (Protobuf, GraphQL, JSON Schema)coveredbuf, graphql-eslint, sourcemeta jsonschemayesbuf breaking gates change
Data modelscoveredSQLFluff, dbt-checkpoint, dbt_project_evaluatoryesnoneConceptual and logical data models have nothing.
Threat modelsopenpytm, Threagilescript your ownnoneNo risk-threshold exit flag anywhere.
Process design against realityplannedProcess-mining conformance checking, for example with PM4Pyscript your ownnoneThe only method that compares a design with what actually happens. Needs an event log.
Vocabulary (glossary)openNo gate. A check that lists terms used repeatedly and defined nowhere exists as an experiment script, not a toolnonenoneAn undefined recurring term is a decision nobody wrote down. On one real program, 42 of 60 recurring terms had no definition measured.
Property-based invariantscoveredA practice, not a tool: property tests on the stated invariants, run against the original and against each rebuildyes, by the test runnernoneReaches behaviour no example scenario states. A property holds for the cases generated, not for all of them.

Projects

Two exist. The others are planned, in the order their feasibility was assessed, and each stays "planned" until a repository exists. A planned project is a statement of intent, not a tool.

pumllint

shipping

A linter and maturity scorer for PlantUML diagrams. The reference implementation of the gate contract, with the measured evidence behind the programme's central claim.

aris2puml

shipping

Converts ARIS process exports to PlantUML activity diagrams so pumllint can gate them. Makes a process checkable; never makes it pass.

Cross-artefact identifier gate

planned

One identifier graph across requirements, models, tests and API operations; fail on orphans and unknown references. Builds on pumllint's trace command.

Requirements wording linter

planned

Deterministic INCOSE and EARS rules with severities and a baseline. Ambiguity detection is reported, never gated, because its precision is too low to block a build.

EPC toolchain in the open

planned

An EPML reader and an EPC conventions ruleset, so process models from any tool that writes the interchange format can be gated.

BPMN repository-wide checks

planned

Cross-model references, pragmatic modelling guidelines and a score, as a bpmnlint plugin.

What a gate can and cannot tell you

A gate answers three questions with decreasing confidence. Is the artefact well-formed and precise? Fully mechanisable, and what the tools above do. Does the design satisfy a property someone stated, such as "every path reaches an end" or "payment never precedes approval"? Mechanisable for process and state models, with the property written by a person. Is the design the right one for the people it serves? Not mechanisable. Every automated check compares an artefact with another artefact; when both are wrong, agreement proves nothing. That question is answered by stakeholders in the room, by a walking skeleton, and by measuring the shipped product. AI reviewers can generate the questions for that room; the 2026 evidence on their agreement with human architects is too weak to let them close it.