Research · v1.0.1

Design Decisions as Validatable Data: A Deterministic Technical Design Specification Pipeline

Lars Shakya Buch-Jepsen

v1.0.1Latest stable release: 2026-11-21

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:

  1. 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];
  2. 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];
  3. 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;
  4. 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 in docs/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 without governs territory 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 by generate-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

  1. 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.
  2. 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.
  3. 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.
  4. Requirements remain natural language. The validator checks the graph around requirement statements, not the statements; requirement quality stays a human discipline [10].
  5. 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.

[1]
J. Tyree and A. Akerman, “Architecture decisions: Demystifying architecture,” IEEE Software, vol. 22, no. 2, pp. 19–27, 2005.
[2]
M. Nygard, “Documenting architecture decisions.” Accessed: Oct. 30, 2026. [Online]. Available: https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions
[3]
L. S. Buch-Jepsen, “Deterministic technical design specification system.” Accessed: Oct. 30, 2026. [Online]. Available: https://github.com/DevelApp-ai/deterministic-technical-design-specification
[4]
Agile Business Consortium, “MoSCoW prioritisation.” Accessed: Oct. 30, 2026. [Online]. Available: https://www.agilebusiness.org/page/ProjectFramework_10_MoSCoWPrioritisation
[5]
O. P. A. contributors, “Open Policy Agent documentation.” Accessed: Oct. 30, 2026. [Online]. Available: https://www.openpolicyagent.org/docs/
[6]
terraform-docs contributors, “Terraform-docs: Generate documentation from Terraform modules.” Accessed: Oct. 30, 2026. [Online]. Available: https://terraform-docs.io/
[7]
R. Hat, “Ansible documentation.” Accessed: Oct. 30, 2026. [Online]. Available: https://docs.ansible.com/
[8]
T. C. Sherwood and MkDocs contributors, “MkDocs: Project documentation with Markdown.” Accessed: Oct. 30, 2026. [Online]. Available: https://www.mkdocs.org/
[9]
Backstage contributors, “Backstage: An open platform for building developer portals.” Accessed: Oct. 30, 2026. [Online]. Available: https://backstage.io/
[10]
S. Bradner, “Key words for use in RFCs to indicate requirement levels.” in Request for comments. Internet Engineering Task Force, 1997. doi: 10.17487/RFC2119.
[11]
L. S. Buch-Jepsen, “FOCUS-Toolkit: Interactive companion toolkit for the Agile Enterprise Playbook.” Accessed: Nov. 20, 2026. [Online]. Available: https://github.com/DevelApp-ai/FOCUS-Toolkit
[12]
B. Meyer, “Applying ‘design by contract’,” IEEE Computer, vol. 25, no. 10, pp. 40–51, 1992.