20 Practical reference

For executable examples and supported options, see the CLI reference and views reference. This chapter summarizes the engineering vocabulary and traceability patterns.

20.1 Configuration map

Engineering policy belongs in .quarto-needs.toml. Quarto presentation settings, including quarto-needs: margin-sidebar-toggle: and tags-page:, belong in _quarto.yml or document metadata.

TOML setting	Purpose and detailed guide
`profile`, `[rules.*]`, `[gates]`	Finding severity, enabled rules and numerical gates: governance.
`[types.*]`	Required attributes, prefixes, semantic roles and allowed statuses: engineering model, authoring and type schemas.
`[relations.*]`	Allowed endpoint types and minimum/maximum cardinality: governance.
`[governance]`	Test/risk types, success and ineffective statuses, and evidence expiry; see the defaults below.
`[queries.*]`	Reusable selections and the full query grammar: named queries.
`[policies.*]`	Scoped declarative assertions: policies.
`[constraints.*]`	Required paths, cycles, connectivity and cardinality: graph constraints.
`[derived.]`, `[variants.]`	Derived attributes and selected build variants: derived values and variants.
`[graph]`	Projection budgets, traversal depth, baselines and overlays: views reference.
`[federation.oslc.profiles.*]`	Endpoint allowlists and bounded OSLC reads: interoperability.

The following [governance] values are the built-in defaults. Change them when your catalog uses different type names or lifecycle statuses:

[governance]
test-types = ["test-case"]
risk-types = ["risk"]
successful-test-statuses = ["passed"]
ineffective-endpoint-statuses = ["disapproved", "rejected", "failed", "deprecated"]
expiry-attribute = "expires"

These settings distinguish the existence of a trace from an effective implementation, successful verification or unexpired evidence. SOURCE_DATE_EPOCH sets the reference date for reproducible date-sensitive analysis; otherwise the engine uses the current date.

20.2 Common types

Type	Suggested role	Common prefix
`stakeholder-need`	`need`	`STK-`
`system-requirement`	`requirement`	`SYS-`
`functional-requirement`	`requirement`	`FUN-`
`non-functional-requirement`	`requirement`	`NFR-`
`architecture-decision`	`decision`	`ADR-`
`component`	`architecture-element`	`COMP-`
`interface`	`architecture-element`	`IF-`
`risk`	`risk`	`RISK-`
`test-case`	`verification`	`TC-`
`evidence`	`evidence`	`EVD-`

These prefixes are conventions, not reserved names. Configure them to fit the project domain.

20.3 Main relations

20.3.1 Requirements

derives-from
refines
decomposes
constrains
depends-on
conflicts-with

20.3.2 Implementation and verification

implemented-by / implements
verified-by / verifies
validated-by
evidenced-by / evidences
mitigates

20.3.3 Architecture decisions

addresses / addressed-by
applies-to
confirmed-by / confirms
supersedes / superseded-by

20.4 Traceability patterns

20.4.1 Requirement to evidence

REQ → implemented-by → Component
REQ → verified-by → Test → evidenced-by → Evidence

20.4.2 Requirement through decision

Requirement ← addresses ← ADR → applies-to → Component
                         └→ confirmed-by → Test

20.4.3 Decision lineage

ADR-002 ──supersedes──► ADR-001

20.5 Interactive graph exploration

The HTML need-graph view combines text search with semantic exploration controls. Type and Status filter nodes; Family restricts the graph to one canonical relation family. These filters compose with the Parents/Children controls, collapse/expand gestures, and fixed-spacing layout.

Traversal selects a canonical semantic profile published by the Python core. The built-in profiles are traceability, derivation, architecture, decision, implementation, verification, and risk. A profile does not reinterpret edge direction in JavaScript: it is a family allowlist over the catalog’s published traversalDirection semantics.

When a node is selected, Path to root finds the nearest semantic root through the active traversal profile and highlights the complete root-to-focus path. This explicit path remains visible even when node filters or the Parents checkbox would otherwise hide an ancestor.

Clicking an edge opens its engineering inspector. The inspector shows the canonical relation family, semantic traversal direction, endpoint roles, impact direction, active profile/filter, and safe declaration provenance (file:line and anchor when available). Only provenance already present in the analyzed snapshot is published; arbitrary source attributes and absolute filesystem paths are not exposed.

Named queries can also be reused as graph views:

{{< need-graph query="accepted-decisions" >}}

or equivalently:

{{< need-graph view="accepted-decisions" >}}

Complex selection remains owned by the Python query engine; the browser controls are presentation filters over an already materialized, bounded public projection.

20.6 Accepted ADR checklist

At minimum, an accepted decision should have stable identity, date, decision makers, a traceable driver, architectural scope, and planned or executable confirmation. Context, drivers, considered options, outcome, consequences, and confirmation should remain readable in the Markdown body.

20.7 Design principle

Use structure only where machines need to query, validate, measure, or traverse. Preserve narrative in Markdown where humans need to explain context and rationale. This balance lets Quarto-Needs remain high-quality documentation without losing formal governance.