Quarto-Needs — Manual

Requirements, decisions and engineering traceability as code

1 Quarto-Needs

Quarto-Needs turns Quarto projects into a traceable engineering platform based on text, Git, and executable documentation. The core treats requirements, architecture decisions, components, interfaces, risks, tests, and evidence as engineering objects connected by typed relations.

The central idea is simple: documentation is not a copy of the engineering model. It is a navigable projection of the canonical model. Semantics live in the Python core; Quarto and Lua handle authoring and presentation.

1.1 What Quarto-Needs provides

  • Requirements as Code in version-controlled .qmd files;
  • stable IDs and configurable types;
  • semantic relations and a traceability graph;
  • structural validation and governance rules;
  • quality gates and coverage metrics;
  • baselines, semantic diff, and impact analysis;
  • tables, matrices, flows, dashboards, and graphs in Quarto;
  • Architecture Decision Management integrated into the same graph;
  • exports for automation and external integrations.

1.2 Self-hosted case study

Quarto-Needs also documents and verifies itself with a complete bilingual engineering model. The rendered case study connects stakeholder needs, requirements, ADRs, architecture, source modules, executable tests, evidence, traceability, and change analysis in one navigable book.

Open the self-hosted Quarto-Needs case study

1.3 Mental model

Stakeholder Need
      │
      ▼
 Requirement ───────► Architecture Decision
      │                    │
      │                    ├──► Component / Interface
      │                    └──► Confirmation
      ▼
Implementation ─────► Test ─────► Evidence

An ADR is not a document maintained in parallel with the requirements process. In Quarto-Needs, an architecture decision is a first-class engineering object that connects drivers to architectural scope and confirmation.

1.4 Manual conventions

Examples use short IDs (REQ-001, ADR-001, TC-001). Prefixes are configurable per type and may include domain namespaces when needed (for example IAM-REQ-001), though a project that already establishes the domain through its own name usually keeps the IDs short.