How Concord works

Record how requirements and specifications map to code and tests in Git. When something changes, Concord follows those links to show which specifications and tests are affected.

One requirement and one property, shared by both APIs

In the official sample, both APIs reference the same requirement. Each API contract defines its own response, and both contracts require the same property about access to private documents.

Requirement R-PRIVATE

Keep private documents visible only to their owners.

Contract C-SEARCH

The search API returns only titles that the viewer may read.

REL-SEARCH-PRIVATERequires
Contract C-DETAIL

The detail API returns HTTP 404 for a document the viewer may not read.

REL-DETAIL-PRIVATERequires
Property P-PRIVATE

An authenticated viewer cannot read a private document they do not own.

Store each Requirement, Contract, Property, and Relation in its own YAML file under concord/ and track them in Git.

Relation connects specifications, code, and tests

A Relation records which property a contract requires and connects that behavior to the code that implements it and the checks that verify it.

Upstream · Requirements and specifications

A Contract references requirement IDs. A Relation identifies the Contract and Property pair.

Relation

Downstream · Implementation and verification

Implementation code implementations
List the paths to the code responsible for the behavior.
Tests and verification commands obligations
Register the tests or commands that check the behavior.

What to check when something changes

When implementation code changes

For a change confined to the search API, follow the Relation linked to the changed code to find the affected specification and checks. The shared property lists src/access.ts as an implementation. Changing it affects tests for both APIs.

When requirements or specifications change

If the access requirement changes, trace it to the affected contracts and properties for search and detail. Before editing the implementation, review which tests need to be added or updated for the new behavior and identify the related code.

View examples