ShallGuard
ShallGuard is requirement-assurance tooling for Cargo projects. It keeps numbered system requirements written in Markdown connected to the Rust code that enforces them and the tests that verify them — and fails CI the moment that connection breaks.
The workspace contains the reusable shallguard library, the
cargo-shallguard Cargo subcommand, and its internal procedural-macro crate.
The project is licensed under the MIT License.
Why "ShallGuard"?
Requirement specifications written in RFC 2119 style use the normative keyword SHALL for mandatory behavior:
REQ-TRACE-004 —
#[shallguard::verifies]SHALL count as automated evidence only on a syntactically recognized, non-ignored test function…
ShallGuard guards the SHALL statements: every SHALL must point at the code that enforces it and the automated test that proves it, and the ratcheted check makes sure a guarded SHALL can never silently lose its evidence again.
How it works
Three ingredients, one deterministic check:
- Requirement documents — Markdown files with numbered requirements
(
REQ-<AREA>-<NNN>), each citing its Enforced: source locations and Verified: tests. - Anchors in code — attributes and macros that mark the enforcement sites and verification tests with the requirement IDs they serve.
cargo shallguard check— cross-checks documents against anchors and fails on dangling references, unanchored requirements, or evidence claims without a real test behind them.
flowchart LR
DOC["Requirement document<br/>REQ-HRS-002: ... SHALL ..."]
CODE["Rust code<br/>#[shallguard::enforces]"]
TEST["Rust tests<br/>#[shallguard::verifies]"]
CHECK{{"cargo shallguard check"}}
DOC -- "Enforced: src/..." --> CHECK
DOC -- "Verified: tests ✅" --> CHECK
CODE -- "enforcement anchors" --> CHECK
TEST -- "verification anchors" --> CHECK
CHECK -- "every SHALL anchored" --> OK(["OK — per-area coverage report"])
CHECK -- "gap or stale reference" --> FAIL(["Nonzero exit — CI fails"])
Deterministic checking needs no network access and no model. Optional
subcommands add executable coverage evidence (via cargo-llvm-cov), Git
change-impact analysis, and local LLM-assisted semantic review.
Installation
Install the published Cargo subcommand:
Or install from a local checkout:
Or pin the CLI to an immutable commit:
Coverage collection additionally requires cargo-llvm-cov. Semantic review
requires a supported provider CLI such as Codex or Claude; deterministic
checking does not require a model provider.
Quick start in your repository
1. Add the library dependency (macros are re-exported through the public
shallguard namespace — no direct macro-crate dependency needed):
[]
= "0.1.0"
2. Create shallguard.toml at the repository root — copy and adapt the
configuration reference:
= 1
= 1
= ".shallguard/baseline.toml"
[[]]
= "docs/USER_STORIES_AND_REQUIREMENTS.md"
= "."
3. Write a requirement in the configured document:
-
4. Anchor it in Rust code:
/// Item-level enforcement: this function exists because the contract exists.
/// Branch-level enforcement: anchor the exact statement, arm, or block.
/// Verification evidence: only a real, non-ignored test counts.
The relation is many-to-many: one item may enforce several requirements, and
one requirement may be enforced in several places. #[verifies] rejects
non-test placements and #[ignore]d tests at compile time — evidence claims
must be honest.
5. Check it:
Adopting around existing code? Create the baseline once, commit it, and shrink it over time — it is a ratchet, not an allowlist:
New gaps always fail; only the exact committed historical gaps are tolerated.
Areas with no remaining gaps can be hardened (hard_enforcement,
hard_verification) so they can never be baselined again.
Command reference
| Command | Purpose |
|---|---|
cargo shallguard check |
Cross-check requirements against code and test anchors (the CI gate). |
cargo shallguard fmt [--check] |
Format (or verify formatting of) requirement blocks. |
cargo shallguard lint |
Lint requirement documents without writing. |
cargo shallguard baseline <check|init|prune> |
Manage the ratcheted gap baseline. |
cargo shallguard impact --base <rev>|--target <branch> |
Map a Git diff to impacted requirements and their tests (JSON/Markdown). |
cargo shallguard test-index |
Enumerate the exact Cargo tests behind verification anchors. |
cargo shallguard coverage |
Collect LLVM execution evidence for verification tests (needs cargo-llvm-cov). |
cargo shallguard bundle |
Build a bounded, auditable source capsule for review. |
cargo shallguard review |
Optional local LLM semantic review of impacted requirements (advisory verdicts). |
cargo shallguard clean |
Remove the validated bundle at the configured artifact location. |
The executable discovers the invoked Cargo repository through
cargo metadata and reads repository-owned policy from shallguard.toml. It
supports ordinary single-package repositories and virtual Cargo workspaces.
Using shallguard as a library
Besides the anchor macros, the crate exposes the deterministic analysis
building blocks (check, scan, impact, coverage, test_index,
baseline, config, review_workflow, …) for embedding requirement
assurance into your own tooling:
use RepositoryConfig;
Library behavior is deterministic and separated from terminal presentation and provider execution; long-running operations report progress through an optional callback instead of printing directly.
CI integration
Add the gate after your ordinary Rust checks — it is fast, deterministic, and needs no secrets:
flowchart LR
subgraph pipeline["CI pipeline"]
direction LR
CO["checkout"] --> FMT["cargo fmt<br/>cargo clippy"]
FMT --> TEST["cargo build<br/>cargo test"]
TEST --> SGF["cargo shallguard fmt --check"]
SGF --> SGC["cargo shallguard check"]
end
SGC -- "no new traceability gaps" --> PASS(["pipeline green"])
SGC -- "requirement lost its anchor<br/>or evidence went stale" --> BLOCK(["pipeline fails —<br/>merge blocked"])
GitHub Actions example:
- name: Requirement assurance
run: |
cargo install cargo-shallguard --version 0.1.0 --locked
cargo shallguard fmt --check
cargo shallguard check
Because the baseline is committed and ratcheted, the gate is monotone: a branch can only keep the gap count equal or lower. Deleting a test, dropping an anchor, or renaming a cited file fails the pipeline immediately.
Merge-request workflow
For behavior changes, the requirement travels with the code in the same MR — spec, enforcement, and evidence are reviewed as one unit:
sequenceDiagram
autonumber
participant Dev as Developer
participant Local as Local checkout
participant CI as CI
participant Rev as Reviewer
Dev->>Local: add / update SHALL requirement in the document
Dev->>Local: implement with #[shallguard::enforces] anchors
Dev->>Local: add test with #[shallguard::verifies]
Dev->>Local: cargo shallguard fmt && cargo shallguard check
Dev->>CI: push merge request
CI->>CI: cargo shallguard check (ratcheted gate)
CI->>CI: cargo shallguard impact --base origin/master
CI-->>Rev: impact artifact — impacted requirements and their exact tests
opt semantic review (local model, advisory)
Rev->>Local: cargo shallguard review --target origin/master
Local-->>Rev: per-requirement verdicts in an auditable run directory
end
Rev->>CI: approve — spec, code, and evidence merge together
The impact artifact answers the reviewer's first questions directly: which
contracts does this diff touch, and which tests prove they still hold?
Model verdicts from review are advisory only; provider or schema failures
return nonzero, but a human decision merges the MR.
Developing ShallGuard itself
This repository defines cargo shallguard-dev as a local alias for its
in-tree binary; CI uses the same command. ShallGuard dogfoods itself: its
committed baseline is empty and every requirement area is hardened, so newly
introduced traceability gaps fail immediately.
See the user documentation, technical documentation, release documentation, configuration reference, glossary, and the requirements specification.