Skip to content

Requirements, design and test documents

wireforge docs <project> -o <dir> writes the documents a software lifecycle needs from the model: requirements, design, test specification, traceability and the checklists around them. The same text comes from GET /api/projects/{id}/docs (a zip) and the MCP tool lifecycle_docs. The output depends only on the model: no date, user name or absolute path is written, so the same model gives the same bytes and the files diff cleanly.

What is written

File Content
index.md baseline (model hash, tool version), list of documents, counts, result of the strict rules, limits
requirements.md, .csv high-level requirements, low-level requirements derived from the model, derived requirements
design.md architecture overview, generated files, interfaces (header, trailer, messages, buffers per profile), messages and types, status codes and the requirements behind them, resources
interfaces_coupling.md data coupling table per interface, control coupling, assumptions
test_spec.md, .csv every generated test: executable, profile, kind, oracle, requirements verified, procedure, expected result
test_report.md test counts; results are not part of this run ("Test results: not provided.")
traceability.md, .csv requirement to model element to LLR to code to test, and tests back to requirements, with the gaps
environment.md model files with sha256, WireForge, Python and library versions
code_standard.md rules the generated code follows and the evidence for each
review_checklists.md checklists for requirements, design, code and tests; items WireForge can decide are answered ([auto: PASS]), the rest are open boxes for the reviewer
do178c_dal_c.md which document is evidence for which DO-178C objective at DAL C; objectives the applicant owns are marked

The directory is created when missing. Only files with these names are written; nothing else in it is touched.

Who writes what

The high-level requirements are yours: write them in the requirements section and point model elements at them with reqs (docs/SCHEMA_SPEC.md section 17). WireForge derives the low-level requirements, links them to the generated tests and writes everything down. A low-level requirement without a high-level one is derived; derived requirements are listed so they can go to the system safety assessment. They are not an error.

--strict

Without --strict the command only fails when the project is invalid. With it, the exit code is 1 when a reviewer would reject the model; each finding is printed and listed in index.md:

Rule Finding
DS-1 the project defines no requirements
DS-2 a message or interface without any high-level requirement behind it
DS-3 a low-level requirement without a generated test (requirements the runtime tests verify are exempt)
DS-4 a requirement verified by test that no model element uses, or that has no requirement vector

With no requirements only DS-1 is reported. The documents are written in any case.

Stable ids, import and export

wireforge reqs-lock writes llr_ids.lock, which gives every low-level requirement a number (SWLLR-00017, or the format you choose) that never changes, is never given again and follows an element through a rename (reqs-rename-key). With the lock file the numbers show in the code comments, the test properties and every document; without it the ids are LLR-<key>. Strict rule DS-8 reports a requirement that has no number yet.

wireforge reqs-import takes a baseline of the high-level requirements of your tool (ReqIF or CSV) as a read-only snapshot, requirements/hlr_snapshot.yaml, with the tool, the baseline name and the hash of the file; a snapshot edited by hand is refused. docs --export reqif writes llr.reqifz, the low-level requirements for your tool, and --source-url 'https://.../{commit}/{path}#L{line}' turns model locations into permalinks (the working copy must be committed). index.md names the baseline: commit, snapshot, number lock, tool and runtime versions. The page docs/DO178C.md shows the whole path; docs/integration lists what to set up per tool.

Test results and coverage

wireforge docs <project> -o <dir> --results <build> adds what a test run produced (docs/CODEGEN.md, "Results of a test run"): test_report.md gets the results per executable and per requirement, the failures, the coverage of the generated code and of the runtime, and the uncovered lines with or without a justification from deviations.yaml; resources.md gets the stack use; environment.md the toolchain; traceability.csv a result column. The run comes from wireforge test <project> -o <dir> --coverage-runtime, which prints the build directory. A missing or damaged result file is an error, never an empty report. The server does not build, so its /docs route has no results.

Strict mode adds three rules when results are given: DS-5 a failed or skipped test, DS-6 generated code below 100 % statement coverage or runtime coverage that was not measured, DS-7 an uncovered line without a justification. Without --results, --strict checks the model only and index.md says "Results: not provided". The generated tests alone do not execute every statement of the runtime, so DS-7 lists what remains; close it with tests or justify it.

The runtime

The generated code relies on the runtime library, which is hand-written. Its requirements are in runtime/requirements.yaml; the project documents show, for each low-level requirement, the runtime requirements that realize its kind (Runtime column of requirements.md) and the runtime version. A requirement that only the runtime tests verify (an unknown message id) counts as tested only when a runtime requirement realizes it, otherwise strict rule DS-3 reports it. The dossier of the runtime itself is ours: wireforge docs --runtime produces it in CI for every release (docs/RUNTIME.md, "Requirements"), and a project refers to it instead of producing it again.

Two kinds of expectation

Most generated tests take their expected result from the reference codec of WireForge (oracle reference-codec). A mistake in how the model is read would then be in both the codec and the generated code, and the tests would stay green. Requirement vectors (docs/SCHEMA_SPEC.md section 18) are written by you from the ICD; their tests carry the oracle hlr-vector in test_spec.md. A requirement verified by test needs at least one vector (rule DS-4); one verified by analysis or review does not, and is listed instead.

What this is not

These documents are evidence for your own process. WireForge does not claim that any output is certified or compliant, and the code generator is not qualified: the generated code is verified like hand-written code, and the documents show that verification (requirement, test, result). The correctness of the high-level requirements, tests on the target and the process around them (planning, configuration management, quality assurance, certification liaison) remain yours. The objective table in do178c_dal_c.md uses our own wording and the objective numbers; confirm the rows marked check against your licensed copy of DO-178C.

quality/run_evidence.sh writes the documents of every example to build/evidence/docs_<project>/.

Change impact

wireforge docs <project> -o <dir> --since <git-revision> also writes impact.md and impact.csv: what a change did since that revision. It lists the high-level requirements that were added, removed or reworded (and a changed baseline of the requirement snapshot), the low-level requirements that were added, removed, reworded or got other parents, the generated files and the declarations in them that changed, the generated tests that were added, removed or changed, and the wire compatibility result of the interfaces. The last section is the list of tests to run and review again: every test that verifies a changed requirement and every test that changed. A test that uses a value derived from a limit changes when the limit changes, so a limit can reach more tests than its own requirement. The old baseline is read from git (git archive) into a temporary directory; the working copy is the new one.

Coding standard and rule checkers

WireForge does not check coding rules. docs/CODING_RULES.md maps the categories of MISRA C++ and AUTOSAR C++14 to the checks that run on generated code and the runtime. A conformance claim needs the results of a licensed checker: wireforge docs <project> -o <dir> --rule-findings report.sarif (repeatable) reads SARIF 2.1.0 or cppcheck XML version 2 and adds the section "Rule findings" to code_standard.md. Only findings in generated headers and in the runtime headers count; the number of findings elsewhere is stated. Per tool and rule, the section lists the findings that have no deviation and the deviations nobody used.

A finding is justified in deviations.yaml with kind: rule: the tool name (case does not matter), the rule as the tool writes it, a file glob, optionally a function glob, the category (justified, false-positive or not-applicable), the rationale and the reviewer. --strict reports DS-9 for every group of findings without a deviation. Without --rule-findings the section says that no results were provided and DS-9 is not evaluated. The MCP tool lifecycle_docs takes rule_findings, a list of files inside the workspace. How to export a report from common tools is in docs/integration/rule_checkers.md.