The primary purpose of the Almirah gem is to control traceability: between specifications on one side, and between specifications and test cases on the other. This page explains what is generated and how to read it.
Processing is two-pass: the first pass collects every controlled-item ID in the project, the second resolves references against them. An up-link you write (>[SRS-001]) becomes a hyperlink, and the down-link — from the requirement back to the item that references it — is generated automatically. You never maintain back-references by hand.
For every pair of linked specification documents (say srs → sad), Almirah renders a traceability matrix: each row pairs a higher-level item with the lower-level items that trace to it. Items with no counterpart stand out immediately — that is how a requirement nobody designed for, or a design item justified by nothing, gets caught.
Test protocols link their steps to requirements via controlled tables (see Markdown Extension). From these, Almirah renders a coverage matrix per specification: which requirements are verified by which test cases, and which are not covered at all. A partially covered document is visible at a glance — try the specification chain demo, which deliberately leaves one item uncovered.
Protocols under tests/protocols/ are non-executed test cases — coverage from them answers “is there a test?”, not “did it pass?”. To capture an execution, copy protocols into a numbered run folder, fill in the results, and select the run:
$ cp -r my_project/tests/protocols/tp-001 my_project/tests/runs/002/
# fill in the Result column and the test summary, then:
$ almirah please my_project --run 002
parsing specifications ..... 2 ok
coverage matrices .......... 1 ok
rendering HTML ............. my_project/build/index.htmlThe coverage matrix now reflects that exact run — with pass/fail results, tester name, and software version from the protocol’s summary table.
There is also a helper for assembling a combined protocol out of several ones:
$ almirah combine my_projectDangling references do not fail the build — they are counted and named in the console output, and highlighted in the rendered HTML:
decision links ............. 38 ok
broken links ............... 1
srs: sys.md
rendering HTML ............. ./build/index.htmlTreat a non-zero broken-links count as a review finding: either the target item was renamed or deleted, or the reference has a typo.
When project.yml declares source repositories, implementation files join the chain via REQ comment tags, and an implementation matrix shows which requirements are realized where. The full chain then reads: requirement → design → code → test — every hop a hyperlink, in both directions.