The graph
The build artifact is a persistent semantic graph, not a report
Five node types
Sections carry the documents' structure. Everything semantic lives in the other four. Nodes are created once and edited in place across builds: a rename keeps the id, a merge leaves a redirect, and a cleared finding resolves instead of vanishing.
Document structure as a parent and child tree. Holds the verbatim text; every quote locates inside it.
A domain concept with one living definition, refined as documents change. One concept, one node, never a per-document copy.
An EARS statement attached to entities, carrying the verbatim source sentence as its quote.
A typed edge between two entities, derived from requirements on every commit. No requirement, no edge.
A recorded judgment: contradiction, ambiguity, duplicate, uncovered section. Sticky by construction: it keeps its id across builds, and a human triage mark (suppressed, wontfix) is never overwritten by the compiler.
On disk
Plain YAML, sorted for clean diffs, under jazyk-out/: one shard per node type, one file per document's section tree and coverage, a journal entry per committed changeset, and a status file with the convergence verdict. From a real build:
ent:order:
name: Order
definition: A transaction where a Customer selects products from the
Catalog, submits them for purchase, and the system reserves Stock and
manages payment and fulfillment.
mentions:
- doc: docs/system.md
section: /orderly
quote: A Customer browses the [Catalog](./catalog.md), places an
[Order](./orders.md), pays through [Payment](./payment.md), ...
created: g1
updated: g26 # definition refreshed by a review turn
req:orders-3:
ears: An Order shall be paid within 14 days of placement, otherwise the
system shall cancel it.
entities: [ent:order, ent:payment]
source:
doc: docs/orders.md
section: /order/lifecycle
quote: An Order shall be paid within 14 days of placement, otherwise
the system shall cancel it.Ids are minted by the store at creation and never change, so generated code, tests, and tickets bind to ent:order and stay bound through renames and merges. The journal records every changeset with the turn's reasoning: the audit trail explains the graph, not just describes it.
Queryable, the same way, everywhere
One context engine assembles bounded packs around any node, with hop quotas and a size budget; whatever the budget cuts off comes back as an expansion handle. The CLI, the MCP server, and the language server all read through it, so an agent asking about ent:order sees exactly what the compiler saw.
$ jazyk context ent:order
## Entity ent:order (Order)
definition: A transaction where a Customer selects products ...
### Requirements
- req:orders-3: An Order shall be paid within 14 days of placement,
otherwise the system shall cancel it. (ties: ent:payment)
- req:payment-1: When a Payment is confirmed, the system shall mark the
Order as paid. (ties: ent:payment)
### More
- h:ent:order|requirements|4 (4 more requirements)Schemas live under docs/compiler and publish at jazyk.org/schemas.