Design Decisions as Validatable Data: A Deterministic Technical Design Specification Pipeline
Lars Shakya Buch-Jepsen
Design Decisions as Validatable Data: A Deterministic Technical Design Specification Pipeline
1. Introduction
Technical design documentation decays for a mechanical reason. A design document is prose, written by hand, at one moment, about code that changes every day. Nothing binds the two: no contract says which paths of the repository a decision governs, no machine can tell whether the document still describes the system, and no review gate notices when someone changes governed code without touching the decision that justified it. The document’s staleness is not a discipline failure; it is the predictable output of a process with no feedback loop.
The architecture-decision-record tradition attacked half of this problem by making decisions first-class versioned artifacts [1], [2]: short, numbered documents, each recording one decision, its context, and its consequences, stored beside the code. The docs-as-code movement attacked the other half by moving documentation authoring and publishing into the same toolchain as code. Neither closes the loop mechanically: an ADR is still prose, its connection to the code still exists only in a reader’s head.
This article presents the deterministic Technical Design Specification (TDS) system [3], an open-source pipeline that closes the loop by treating design documents as data. The system is shipped as a working example repository whose pipeline:
- declares — every ADR carries structured front-matter naming the requirement ids it implements and the repository paths it governs; every OPA policy carries a metadoc naming the ADR and requirements it relates to; requirements are machine-readable MoSCoW Markdown [4];
- validates — a deterministic scanner folds those declarations into an architecture catalog, and Rego rules check the catalog the way a compiler checks a program: duplicate ids, cyclic or dangling supersedes chains, status mismatches, ADRs without requirements or territory, defective policy metadocs — fourteen explicit findings in the shipped rule set [5];
- enforces — a pull-request boundary gate fails any PR that changes a governed path without citing the governing ADR, and the CI pipeline blocks merges on policy violations before a single human reads the diff;
- regenerates — documentation artifacts, including traceability diagrams, are auto-generated from source, byte-identically; a committed artifact that has drifted from its own regeneration fails the build.
The companion article on specification recovery
(spectree-search-based-specification-recovery in this
repository) addresses the inverse problem — recovering specification
structure from code that has none. This article addresses the forward
path: authoring design structure up front so it can be validated,
enforced, and diffed like code.
The claims that matter here are verifiable by construction: the pipeline either blocks a non-citing PR or it does not; the catalog validator either has fourteen findings or it has fewer; regeneration is either byte-identical or it is not. Section 9 separates these from the claims that need a measurement campaign, which are stated as projected.
1.1 Contributions
- the three-way determinism contract and its pipeline (Section 3);
- the data model of design artifacts — ADR front-matter, MoSCoW Markdown, Rego metadocs — and the architecture catalog built from them (Section 4);
- the validation and enforcement layers: catalog findings, bounded chain resolution, and the PR boundary gate (Sections 5–6);
- the write-once compliance consequence and its browser-only authoring companion (Sections 4.5–4.6);
- the determinism discipline — byte-identical generation, drift detection, inverted-expectation demonstration (Section 7);
- and a claim ledger that separates by-construction verifiable properties from projected ones (Section 9).
2. Background
Decisions as records. Tyree and Akerman argued that the decisions behind an architecture are the architecture’s most valuable and least documented artifact [1]; Nygard’s ADR template made the practice operational — one short document per decision, stored in the repository, in plain view [2]. The practice spread because it matches how design knowledge actually accumulates: incrementally, locally, and mostly in the past tense.
Docs as code. Treating documentation with the same toolchain as code — version control, review, CI, generated artifacts — removed the process split between “writing” and “engineering” and made stale documentation at least visible in diffs. Auto-generation tools (terraform-docs for Terraform modules [6], Ansible fact reports through Jinja2 templates [7]) cover the artifacts whose truth lives in code; MkDocs and static-site generators cover publishing [8]; Backstage’s TechDocs integrates documentation into the developer portal where the organization already works [9].
Policy as code. OPA’s Rego language made over-documented rules executable: a policy that declares required cost-allocation tags, and blocks the plan that violates them, is documentation that cannot go stale in the relevant sense — it fails loudly instead [5].
The TDS system sits at the intersection: it applies the policy-as-code machinery to the design documentation layer itself. ADRs, requirements, and policy metadata become inputs to a validator and a gate, exactly as Terraform plans are inputs to a policy engine.
3. System Overview: The Three-Way Contract
The example repository states the system’s contract in three sentences, and the whole design follows from them. Every piece of published documentation is either:
- auto-generated from source — Terraform modules
through terraform-docs; host configuration facts through Ansible
playbooks rendering Jinja2 templates to deterministic Markdown; OPA
policy summaries from
__rego__metadoc__blocks; - version-controlled Markdown co-located with the code it
describes — ADRs in
docs/adrs/, MoSCoW requirements indocs/requirements/; - or nothing — “nothing is written manually after the fact.”
The first branch removes staleness for artifacts whose truth lives in code; the second makes the remaining prose a first-class reviewed artifact; the exclusion clause is the discipline that keeps the other two honest.
Around the contract sits a conventional, fully scripted pipeline:
Pull Request
│
▼
OPA Tests (opa test)
│
▼
Terraform validate + plan, OPA policy gate
│
▼
Docs build (terraform-docs, Ansible, MkDocs)
│
▼
GitHub Pages deploy (main only)
The toolchain is containerized (a multi-stage Docker image with pinned versions), publishable both as a static MkDocs site and as a Backstage portal with TechDocs, and the whole flow runs in GitHub Actions on every pull request. A PR introducing a policy violation — a resource missing a required FinOps cost-allocation tag, for example — cannot be merged; the denial message is the job output.
The repository is also self-hosting in a way worth naming: the ADR traceability kit described in Section 5 is itself governed by an ADR (ADR-0012), scanned by its own scanner, and validated by its own rules. The system’s dogfooding is enforced by the system.
4. Design Artifacts as Data
4.1 ADR Front-Matter
Each ADR is ordinary Nygard-style prose — context, decision, consequences — preceded by structured front-matter. Two fields carry the load:
related_requirements:the ids of the MoSCoW requirements the decision implements;governs:the repository paths the decision protects. An accepted ADR withoutgovernsterritory is flagged by the validator — a decision that protects nothing is recorded as such, loudly.
The prose remains for humans; the front-matter is for the machines that must connect decisions to code and to each other.
4.2 Machine-Readable MoSCoW Requirements
Requirements live as Markdown with a machine-readable table — id, priority (Must/Should/Could/Won’t in the MoSCoW discipline [4]), statement — so the same file serves both as the reviewed requirement document and as the requirements database the validator joins against. The requirement-keyword discipline follows the long-established convention of unambiguous requirement language [10]: statements are checkable, and the validator checks the graph around them rather than their natural-language truth.
4.3 Self-Describing Policy Metadocs
Each Rego policy carries a __rego__metadoc__ block
declaring its id, its related_adr, and its
related_requirements. A policy without a metadoc, or a
metadoc pointing at a nonexistent ADR, is a validator finding. The
metadoc convention also gives the compliance page its content: the
published policy summary is generated from the same metadata the gate
enforces, so the documentation and the enforcement cannot disagree.
4.4 The Architecture Catalog
A scanner (scan-architecture.py, deliberately
stdlib-only Python) reads the three declaration surfaces and folds them
into a single JSON artifact, the architecture catalog: every ADR with
its status, requirements, territory, and supersedes edges; every policy
metadoc; every requirement id. The catalog is the compilation unit of
the whole system — a small, inspectable, deterministic snapshot of the
design layer that everything downstream consumes.
4.5 Write Once, Generate Everywhere: Compliance as a Byproduct
The three-way contract has an economic reading that is worth stating
explicitly, because it is the reason the discipline holds up under time
pressure. Every governance fact in the system is written exactly once:
the decision is written once, as an ADR with front-matter; the
requirement is written once, as a MoSCoW row; the policy relation is
written once, as a metadoc. Everything else governance needs is
generated from those single writes: the architecture catalog is
generated, the traceability diagram is generated, the compliance page
that summarizes each policy is generated from the very metadoc the gate
enforces (Section 4.3), and the PR citation requirement is resolved from
the front-matter’s governs: territory.
This is compliance made easy, by construction. What makes compliance regimes expensive in practice is not the audit but the duplicated record-keeping around it: the decision is explained in a review, restated in a wiki, summarized at a gate, and each restatement drifts independently. Under the write-once contract there is no restatement to drift. The engineer who authors the declaration correctly has, with no further effort, produced the authoritative answer to every downstream compliance question: what governs this path, which requirement this policy traces to, which decision this PR must cite. The audit trail is the design record, and it is regenerated from the same source the gate enforces, so the two cannot disagree.
4.6 The Authoring Side: A Browser-Only Companion App
The declaration layer is the system’s only hand-written surface, so it is also the only place where authoring friction can erode the discipline: front-matter is schema-shaped but hand-typed, and a typo in a requirement id or a supersedes reference surfaces only when CI runs. The repository therefore ships a companion authoring application: a browser-only static web app, published on GitHub Pages in the deployment posture of the FOCUS Toolkit companion tools [11], built for exactly the artifacts that cannot be generated.
The app is deliberately narrow. It provides form-based editing of ADR
front-matter (id suggestion, requirement-id selection from the loaded
requirement files, supersedes chaining, governs: globs),
editing of the machine-readable MoSCoW tables, and editing of policy
metadocs. It renders a read-only view of the generated catalog: decision
chains, territory, and effective decisions. It runs a client-side mirror
of the validator’s fourteen findings and the eight-hop chain bound,
using the same finding names CI prints, so that authoring-time feedback
and pipeline feedback match in vocabulary. And it includes a citation
helper that resolves, for a changed path, the ADR a pull request must
cite.
Two boundaries keep it honest. First, locality: the app carries its knowledge (schemas, enumerations, findings) in the browser, connects to no server, makes no request after load, and reads and writes the repository’s actual source files in place through the File System Access API, with a download/upload fallback. A contributor’s design files never leave the machine. Second, authority: the app is a pre-flight linter, not a gate; the merge gate re-checks everything on the pipeline, and the files the app writes are source declarations only, never published artifacts, so the regeneration contract of Section 7 is untouched.
5. Validation: Checking the Design Like a Program
The catalog is validated by Rego rules, the same engine that gates the infrastructure plans — a deliberate reuse: the design layer gets the machinery proven in the enforcement layer. The posture is the design-by-contract idea transposed from module interfaces to documentation [12]: obligations are attached to the declarations themselves and checked mechanically rather than by reviewer vigilance.
validate.rego — fourteen loud findings.
The shipped rule set checks: duplicate ids across the catalog; cyclic
supersedes chains; dangling supersedes references; status/chain
mismatches (an ADR marked Accepted while superseded, a superseding ADR
that is itself not current); ADRs with no related requirements; accepted
ADRs with no governed territory; policy metadoc defects. Fourteen
findings, each named, each reported with the offending id — the
diagnostic posture of a linter, not a review comment.
chain.rego — bounded, loud closure.
Resolving “which ADR is currently effective” requires traversing
supersedes chains, and Rego deliberately forbids recursion. The shipped
rule implements closure with an explicit eight-hop bound: chains deeper
than eight hops are resolved as an over-depth finding rather than
silently misresolved. The bound is chosen, documented, and fails loudly
— the honest alternative to pretending unbounded recursion is
possible.
The findings philosophy is consistent throughout: every check that would otherwise be a human’s vigilance (“does the new ADR supersede one that’s already superseded?” “does this policy actually trace to a requirement?”) becomes a rule, and every rule reports loudly or not at all.
6. Enforcement: The PR Boundary Gate
Validation finds defects; enforcement prevents them from landing. The
boundary gate (gate.rego +
architecture-gate.sh) runs in the CI pipeline and answers
one question per PR: does this change touch a governed path without
citing the governing decision?
Mechanically: the gate diffs the PR’s changed paths against the
governs: territory declared in ADR front-matter; for any
overlap, the PR description must cite the governing ADR
(ADR-####); a failure names the path and the ADR that must
be cited. Superseded ADRs do not satisfy the gate — the gate resolves
through the chain and redirects the citation requirement to the
successor, so citing an obsolete decision is itself caught.
The gate inverts the usual economics of design review. A human reviewer must notice that a change contradicts a decision; the gate requires only that the author acknowledge the decision’s existence before the merge. Acknowledgment is cheap to demand, impossible to forget, and produces the citation trail in the PR history that later archaeology needs.
The demonstration script ships the done-when scenario with inverted
expectations, a detail that matters for honesty: the kit’s test proves
that a governed change without an ADR citation is blocked, that
the same change with a citation passes, that a superseded link
is redirected to its successor, and that diagram regeneration is
cmp-identical — it demonstrates the failure modes
as first-class behavior, not just the happy path.
The enforcement surface has since grown in ways the same architecture predicted. A nightly drift gate re-plans the governed infrastructure and fails when reality has drifted from what the pipeline last validated; inbound representative-specification suites are ingested as first-class declaration artifacts with their own metadata contract and an OPA validation gate before their structure reaches the catalog; and an explicit AI/LLM boundary records that language-model tooling may consume TDS artifacts but never produces them, keeping the declaration layer human-authored and the pipeline’s guarantee intact [3].
7. Determinism Discipline
The system’s namesake property is that its outputs are functions of its inputs:
- The scanner is deterministic and dependency-free — stdlib-only Python, no parsing frameworks, no network, ordered traversal — so the catalog is reproducible byte-for-byte.
- Generated diagrams are regenerated, not edited. The
traceability diagram (
traceability.drawio) is produced bygenerate-traceability.py, and CI regenerates and compares: a committed diagram that has drifted from its own regeneration fails the build. The diagram is data about the catalog, and the catalog is data about the declarations — the diagram cannot lie independently. - Living configuration reports are rendered from gathered facts through Jinja2 templates to deterministic Markdown, so a configuration page is a rendering of the host’s actual state, not a description of last year’s host.
- Publishing is generated. The MkDocs site, the Backstage TechDocs bundle, the terraform-docs module pages — all built in the pipeline, deployed on merge, never hand-edited.
The determinism contract is what makes “nothing is written manually after the fact” enforceable rather than aspirational: anything that is written manually cannot survive regeneration, so manual edits are structurally discouraged rather than merely discouraged by policy.
8. Traceability: The Graph a Reviewer Actually Needs
The declarations, catalog, and gates compose into the artifact design review always wanted and rarely had: a traversable graph from requirement to decision to enforcement. A MoSCoW requirement links to the ADRs that implement it; an ADR links to the policies and governed paths that protect it; a policy links back to its requirements. The traceability page renders this as Mermaid diagrams for humans, the generated drawio diagram for the book-convention renders, and the catalog JSON for machines.
The consequence for review is concrete: a proposal to change a governed path arrives with its blast radius already computed — which ADR, which requirements, which policies — and the citation requirement makes the acknowledgment explicit in the PR record. What a reviewer previously reconstructed from memory and tribal knowledge is now a join over declared data.
9. Evaluation Status
Evaluation status. The TDS pipeline is shipped and demonstrated: the scanner, the fourteen-finding catalog validator, the bounded chain resolver, the PR boundary gate, the byte-identical diagram regeneration, and the inverted-expectation demonstration all run in the example repository’s CI. The claims in this article are deliberately restricted to what is verifiable by construction: determinism (regeneration is byte-identical or the build fails), enforcement (a governed change without a citation blocks the merge, demonstrated), and validation (the finding set exists and fires on seeded defects). The companion app makes the same kind of claim: it either runs entirely client-side or it does not, and its client-side findings either agree with the CI verdicts on the seeded-defects corpus or they do not. No claims are made about effects on review quality, design-drift rates, or adoption: those require a measurement campaign across real projects and are stated as projected hypotheses — tracked in the companion measurement issue per the repository’s measurement discipline.
The projected hypotheses, for the record: (i) governed paths change with citations more often once the gate is active than before; (ii) catalog findings appear mostly at authoring time, not review time; (iii) the cost of front-matter discipline is repaid in review latency for cross-cutting changes. Each is falsifiable; none is claimed.
10. Limitations
- Example-scale repository. The shipped system demonstrates the pipeline on a local-provider Terraform example; running it against a large, multi-team repository is a deployment exercise, with the scanner’s cost profile unproven at that scale.
- The eight-hop bound. Chain resolution is bounded by design; a supersedes chain deeper than eight hops is a loud finding, not a resolved chain. Repositories that accumulate decade-scale decision archaeology must either accept the bound or extend it consciously.
- Gate granularity is the path. The
governs:model is directory/file-path based; semantic enforcement (which kind of change to a governed file matters) remains a human question. - Requirements remain natural language. The validator checks the graph around requirement statements, not the statements; requirement quality stays a human discipline [10].
- Single-language metadoc convention. The traceability kit’s conventions are demonstrated for Rego policies; policies written in other engines need their own metadoc adapters.
11. Conclusion
The deterministic TDS system treats design documentation the way the field long ago learned to treat infrastructure: as declarations with consequences. Decisions declare the paths they govern; policies declare the decisions they implement; requirements are rows, not paragraphs. A scanner compiles the declarations into a catalog, Rego rules check the catalog the way a linter checks code, a gate blocks the merges that skip the decisions, and regeneration — byte identical, drift-detecting — keeps the published artifacts honest by construction.
The claims were kept deliberately modest and deliberately checkable: the pipeline demonstrably blocks, validates, and regenerates, and everything else is labeled projected. That modesty is the point. A design-review mechanism earns trust the same way a compiler does — not by promising better programs, but by failing predictably when the program is wrong.