Using the OSQAr Boilerplate¶

This chapter is the main entrypoint for OSQAr. It explains the mental model (project → shipment → workspace) and provides copy/paste workflows.

For the full per-command reference (all flags, exit codes, and resolution rules), see CLI Reference.

What OSQAr Is For¶

OSQAr is a documentation-first framework for producing, verifying, and integrating auditable evidence shipments for safety/compliance work.

An evidence shipment is the unit you transfer and archive: a bundle that contains:

rendered Sphinx documentation (with traceability)
implementation sources and tests
verification artifacts (test reports, analysis summaries, traceability reports)
integrity protection (checksum manifest)

OSQAr’s core ingredients:

structured requirements and traceability (via sphinx-needs)
architecture diagrams (via PlantUML)
verification planning (requirements ↔ architecture ↔ tests)
shipment and workspace workflows (prepare, verify, intake, report)

How To Use This Guide¶

Run Quick Start (End-to-End) to build docs and generate a scaffold.
Read Terminology (Project, Shipment, Workspace) once (project vs shipment vs workspace).
Use Workflow Recipes as your day-to-day command cookbook.
When you need exact flags/help, jump to CLI Reference.

Quick Start (End-to-End)¶

Note

The examples below use the PyPI-installed CLI.

Install OSQAr once: pipx install osqar
Invoke commands as: osqar <command> ...

If you are contributing to OSQAr from a git clone and did not install via pipx, use the repo-root wrappers instead (./osqar on Linux/macOS; osqar.cmd / osqar.ps1 on Windows).

# 0) Install the OSQAr CLI
pipx install osqar

# 1) Install dependencies (this repo / framework docs)
poetry install

# 2) Build the framework docs (repo root)
osqar build-docs

# 3) Scaffold a minimal project next to the framework repo
osqar new --language c --name MySEooC --destination ../MySEooC

# 4) Build the scaffolded project docs
osqar build-docs --project ../MySEooC

Windows note: prefer the Windows repo-root wrappers (osqar.cmd / osqar.ps1). If you want to run the example *.sh scripts unchanged, use WSL2.

Workflow overview¶

Author needs objects (REQ/ARCH/TEST) in RST with stable IDs.
Build HTML docs and export machine-readable artifacts (e.g. needs.json).
Run traceability checks and keep the report.
Generate a checksum manifest (e.g. SHA256SUMS).
Transfer/archive the shipment; integrators verify checksums and (optionally) re-run checks.

Installation options (Poetry groups)¶

OSQAr keeps the default Python dependency footprint lean. Install additional tooling only if you need it:

Core docs + CLI (recommended default):
```
poetry install
```
Evidence tooling (coverage/complexity generation used by example scripts):
```
poetry install --with evidence
```
IDE tooling (optional Sphinx language server for VS Code):
```
poetry install --with ide
```

Download (optional)¶

If you want pre-built archives (example workspaces / demo shipments) without building locally, use the GitHub Releases assets:

https://github.com/bitvortex/OSQAr/releases

If you downloaded the combined example workspace ZIP from Releases (often together with a .sha256 file), extract and verify it with:

osqar setup osqar_example_workspace_<tag>.zip

Terminology (Project, Shipment, Workspace)¶

These terms are used consistently across the docs and the CLI. They match the definitions in CLI Reference.

Project (shipment project)¶

Directory that contains at least:

conf.py
index.rst

Examples live under examples/.

Shipment directory (built evidence output)¶

The built HTML output directory, usually:

<project>/_build/html

This directory may contain artifacts such as index.html, needs.json, SHA256SUMS, and reports.

Workspace (integrator side)¶

A directory that contains multiple received shipments. Workspace commands typically discover shipments by scanning for SHA256SUMS in subdirectories.

Declared dependencies (pins)¶

OSQAr supports workspace dependency closure for OSQAr-qualified libraries. If a shipped component depends on other OSQAr-qualified components, the supplier can declare those dependencies in the shipped osqar_project.json.

Each dependency is identified by:

id
version
pin_sha256sums (a SHA-256 over the dependency shipment’s SHA256SUMS file bytes)

Suppliers can compute the pin from a built/received shipment directory:

osqar shipment pin --shipment /path/to/LIB_PROVIDER_shipment

Integrators can enforce that all declared dependencies are present (and unambiguous) in a workspace:

osqar workspace verify --root intake/received --recursive --enforce-deps

See Multi-project workflows for the full dependency resolution rules and how to observe logical deduplication.

Workflow Recipes¶

The commands below are the “core loop” you’ll run most often.

Build docs (Sphinx HTML)¶

# Build docs for the current project (default: --project .)
osqar build-docs

# Build docs for an example project
osqar build-docs --project examples/c_hello_world

# Build and open index.html
osqar build-docs --open

Verify traceability¶

OSQAr’s traceability check validates basic rules based on exported needs.json.

osqar traceability ./_build/html/needs.json \
  --json-report ./_build/html/traceability_report.json

Checksum manifest (shipment integrity)¶

Generate and verify a checksum manifest (default: SHA-256) for a shipped directory.

osqar checksum generate \
   --root ./_build/html \
   --output ./_build/html/SHA256SUMS \
   --json-report ./_build/html/checksums_report.generate.json

osqar checksum verify \
   --root ./_build/html \
   --manifest ./_build/html/SHA256SUMS \
   --json-report ./_build/html/checksums_report.verify.json

Prepare and verify a shipment (high-level)¶

If you want one command that builds docs, runs checks, and optionally archives:

# Supplier side: build a shippable evidence directory
osqar shipment prepare --project examples/python_hello_world --clean --archive

# Integrator side: verify a received shipment
osqar shipment verify --shipment /path/to/shipment --traceability \
   --report-json /path/to/shipment/verify_report.json

Reproducible native builds (C / C++ / Rust)¶

OSQAr’s documentation builds are already dependency-locked via Poetry. For native code (C/C++/Rust), OSQAr also provides a small “reproducible build” mode in the examples.

The goals are:

stable timestamps (via SOURCE_DATE_EPOCH)
stable embedded source paths (via compiler path remapping)
reduced build-environment noise (UTC timezone + stable locale)

The example build scripts accept either the environment flag OSQAR_REPRODUCIBLE=1 or the CLI flag --reproducible.

# Use the latest git commit timestamp as a stable build time
export SOURCE_DATE_EPOCH="$(git log -1 --format=%ct)"

# C example
cd examples/c_hello_world
OSQAR_REPRODUCIBLE=1 ./build-and-test.sh

# C++ example
cd ../cpp_hello_world
OSQAR_REPRODUCIBLE=1 ./build-and-test.sh

# Rust example
cd ../rust_hello_world
OSQAR_REPRODUCIBLE=1 ./build-and-test.sh

Notes:

The reproducible mode is implemented as a small helper script (vendored into each example at osqar_tools/reproducible_build_env.sh) and is intentionally lightweight.
The shipped test report XML in the examples does not include timestamps, so it is stable across runs.

Optional: Bazel integration¶

If you prefer Bazel for a more “CI-native” workflow, the C, C++, and Rust examples include minimal Bazel files.

Reproducible mode for Bazel is supported via the wrapper script in each example (it applies the same path remapping and stable environment as the non-Bazel scripts, and runs Bazel with --config=reproducible).

cd examples/c_hello_world
# Non-reproducible (default)
bazel build //...
bazel run //:junit_tests -- test_results.xml

# Reproducible
export SOURCE_DATE_EPOCH="$(git log -1 --format=%ct)"
OSQAR_REPRODUCIBLE=1 ./bazel-build-and-test.sh

cd ../cpp_hello_world
bazel build //...
bazel run //:junit_tests -- test_results.xml

export SOURCE_DATE_EPOCH="$(git log -1 --format=%ct)"
OSQAR_REPRODUCIBLE=1 ./bazel-build-and-test.sh

cd ../rust_hello_world
bazel build //...
bazel run //:junit_tests -- test_results.xml

export SOURCE_DATE_EPOCH="$(git log -1 --format=%ct)"
OSQAR_REPRODUCIBLE=1 ./bazel-build-and-test.sh

CI-built demo shipments (downloadable)¶

This repository’s CI builds downloadable, integrity-protected example shipments for the C, C++, and Rust examples.

Each example shipment contains:

rendered HTML documentation (with maintained traceability)
implementation sources and tests
analysis/verification reports:
- test_results.xml (JUnit)
- coverage_report.txt (coverage summary; language-specific tooling)
- complexity_report.txt (complexity summary)
needs.json (trace graph export)
traceability_report.json (OSQAr traceability validation output)
SHA256SUMS (checksum manifest for the whole bundle directory)

CI exports deterministic archives (.tar.gz) for each example as well as a combined archive. CI exports deterministic-ish ZIP archives for each example shipment and a combined example workspace. In GitHub Actions, download the artifact named osqar-example-workspace from the Tests and Example Shipments workflow run.

For the repository’s CI configuration (including reproducible build settings), see CI setup (GitHub Actions).

Reference examples¶

OSQAr primarily targets C, C++, and Rust projects.

Each example produces:

native test results as test_results.xml (JUnit)
rendered HTML documentation; the examples can optionally import JUnit XML into the docs via sphinx-test-reports

Build any example documentation directly:

poetry install
osqar build-docs --project examples/c_hello_world
osqar build-docs --project examples/cpp_hello_world
osqar build-docs --project examples/rust_hello_world

Run an end-to-end workflow (native tests → docs) for an example:

# Optional: install extra tooling to generate coverage/complexity evidence
poetry install --with evidence

cd examples/c_hello_world
./build-and-test.sh
open _build/html/index.html

Python demo (workstation reference)¶

A Python example remains available as a documentation reference variant:

# Optional: install extra tooling to generate coverage/complexity evidence
poetry install --with evidence

cd examples/python_hello_world
./build-and-test.sh
open _build/html/index.html

OSQAr CLI¶

OSQAr includes a small, stdlib-only CLI for common workflows:

scaffold a new project from a language template
validate traceability based on an exported needs.json
generate/verify checksum manifests for a shipped evidence bundle
supplier and integrator workflows (prepare, verify, intake)
optional shipment metadata (origin, URLs, descriptive info)

For guidance on large-team collaboration (branching, merging, conflict minimization), see Collaboration workflows (multi-user).

Full command reference (all subcommands and flags): CLI Reference.

Shell scripts and Windows support¶

OSQAr includes a number of shell scripts (primarily *.sh) across the repository. They exist for two reasons:

Example automation and CI parity: the example projects (C/C++/Rust/Python) ship
end-to-end scripts (tests → evidence files → docs) so users can reproduce what the CI and GitHub Pages workflows do.
Developer convenience: a small number of scripts help with local workflows.

Design decision (pragmatic cross-platform support)¶

This repository intentionally does not try to provide a Windows-native equivalent for every .sh script.

Reasons:

Many scripts assume a POSIX shell and common Unix tooling (Bash, coreutils, path
conventions, executable bits).
Reproducible-build packaging is much harder to keep consistent across platforms
(e.g., stable ZIP creation, stable file ordering, stable timestamps).

Instead, OSQAr uses:

A cross-platform primary entry point: the installed CLI (osqar).
Repo-root wrappers for contributors and offline use (./osqar on Linux/macOS; osqar.cmd / osqar.ps1 on Windows).
A documented fallback for running example scripts on Windows: WSL2 (recommended)
or a POSIX-like environment such as Git Bash.

What this means in practice¶

If you are on Windows and want the supplier/integrator workflows, prefer the CLI. It covers the common steps (build docs, run traceability checks, generate/verify checksums, archive shipments).
If you specifically want to run the example build-and-test.sh scripts unchanged, run them in WSL2.

Support matrix¶

Support matrix (recommended expectations)¶
Workflow	Linux/macOS	Windows (native)	Windows (WSL2)
Run OSQAr CLI workflows (scaffold, traceability, checksums, supplier/integrator)	Supported	Supported (recommended)	Supported
Run example `build-and-test.sh` scripts unchanged	Supported	Not supported (use CLI, or run under WSL2)	Supported (recommended)
Reproducible builds and deterministic shipment archives	Supported (CI reference)	Best-effort (tooling differences)	Supported (closest to CI)

Windows-friendly equivalents (recommended)¶

The following are intended as portable alternatives to the example scripts:

# Build docs and prepare an evidence shipment via the CLI
osqar shipment prepare \
    --project examples/python_hello_world \
    --clean \
    --archive

For more context on the CI workflows and how these scripts are used in automation, see CI setup (GitHub Actions).

Scaffold a new project¶

Create a new project folder based on one of the reference templates:

For a step-by-step guide (including how to migrate existing sources and documentation, and how to ship a release with OSQAr evidence), see Setting Up A Project From Scratch.

osqar new --language c --name MySEooC --destination ./MySEooC

This copies the selected template while excluding build outputs (e.g., _build/, target/, __pycache__/).

Verify traceability¶

Run traceability checks on an exported needs.json:

osqar traceability ./_build/html/needs.json \
  --json-report ./_build/html/traceability_report.json

Checksum manifest (shipment integrity)¶

Generate and verify a checksum manifest (default: SHA-256) for a shipped directory:

osqar checksum generate \
   --root ./_build/html \
   --output ./_build/html/SHA256SUMS \
   --json-report ./_build/html/checksums_report.generate.json

osqar checksum verify \
   --root ./_build/html \
   --manifest ./_build/html/SHA256SUMS \
   --json-report ./_build/html/checksums_report.verify.json

Core authoring workflow¶

OSQAr works best when you keep a consistent structure:

define requirements and constraints as .. need:: objects with stable IDs
link requirements ↔ architecture ↔ tests using :links: and :need:`ID` references
keep architecture diagrams in PlantUML sources under version control
define verification requirements (TEST_*) and include traceability tables/matrices (e.g. via sphinx-needs directives)

Writing requirements (sphinx-needs)¶

A requirement is defined using a .. need:: directive with a stable :id:.

.. need:: (SR) Detect overheat within 100ms.
   :id: REQ_SAFETY_002
   :status: active
   :tags: timing
   :links: REQ_SAFETY_001, ARCH_FUNC_003, TEST_END_TO_END_001

   **Architecture**: :need:`ARCH_FUNC_003`
   **Tests**: :need:`TEST_END_TO_END_001`

Recommended ID scheme¶

The boilerplate enforces ID discipline via needs_id_regex.

A practical scheme is:

REQ_SAFETY_*: safety goals and safety requirements
REQ_FUNC_*: functional requirements
ARCH_*: architecture/design constraints and interfaces
TEST_*: verification requirements / test specifications

Architecture diagrams (PlantUML)¶

PlantUML sources live in diagrams/ and are included from RST:

.. uml:: diagrams/02_data_flow.puml
   :caption: Data flow (budget: :need:`REQ_SAFETY_002`) — Architecture: :need:`ARCH_FUNC_001`, :need:`ARCH_FUNC_002`, :need:`ARCH_FUNC_003`

Verification and traceability¶

A robust verification chapter typically contains:

test requirements as needs objects (TEST_*)
a traceability matrix mapping REQ_*/ARCH_* → TEST_*

Traceability into source code (“best of both worlds”)¶

In practice, teams often want two complementary views of traceability:

Documentation-level traceability (auditor-friendly): REQ_* ↔ ARCH_* ↔ TEST_* links in Sphinx via sphinx-needs.
Code-level traceability (engineer-friendly): the same IDs appear in implementation and test code comments near the relevant functions.

OSQAr supports using both together:

In the docs, create a code-level need (commonly CODE_* or IMPL_*) as an evidence anchor. Link it to the corresponding REQ_*/ARCH_*/TEST_* needs, and embed/attach the actual sources:
- Use literalinclude to embed excerpts directly into the shipped HTML.
- Use :download: to attach full files for review.
In the code, tag the relevant locations with IDs so reviewers can find the implementation quickly. Examples (language-agnostic):
- Implementation: mention REQ_* and ARCH_* near the function/module that implements it.
- Tests: mention TEST_* near the test that realizes the verification requirement.

Optional CI check: validate IDs in code¶

To keep the code tags from drifting, you can scan sources and optionally enforce simple coverage rules.

Generate a report (non-failing by default):

osqar code-trace \
   --root . \
   --needs-json ./_build/html/needs.json \
   --json-report ./_build/html/code_trace_report.json

Enforce that every documented ID is mentioned in code (useful in CI):

osqar code-trace \
   --root . \
   --needs-json ./_build/html/needs.json \
   --enforce-req-in-impl \
   --enforce-arch-in-impl \
   --enforce-test-in-tests

Shipment verification (per example output)¶

OSQAr treats each example build output directory as a shippable evidence bundle. This is the unit that is transferred, archived, and later verified (similar to a software shipment).

Per shipped example output directory, OSQAr expects the following files to be present:

needs.json (export from sphinx-needs)
traceability_report.json (result of the OSQAr traceability check)
SHA256SUMS (checksum manifest covering the full directory contents)
osqar_project.json (optional project metadata: description, URLs, origin)

Supplier-side procedure (create the shipment)¶

Build the example documentation so that needs.json is exported:

osqar build-docs --project examples/python_hello_world

Run the traceability check (writes a machine-readable report):

osqar traceability examples/python_hello_world/_build/html/needs.json \
   --json-report examples/python_hello_world/_build/html/traceability_report.json

Generate and verify checksums for the example build output directory:

osqar checksum generate \
   --root examples/python_hello_world/_build/html \
   --output examples/python_hello_world/_build/html/SHA256SUMS \
   --json-report examples/python_hello_world/_build/html/checksums_report.generate.json

osqar checksum verify \
   --root examples/python_hello_world/_build/html \
   --manifest examples/python_hello_world/_build/html/SHA256SUMS \
   --json-report examples/python_hello_world/_build/html/checksums_report.verify.json

Optional convenience (higher-level workflows in one command):

# Build a shippable evidence directory in one command
osqar shipment prepare \
   --project examples/python_hello_world \
   --clean \
   --archive

# Verify a received shipment (checksums + traceability)
osqar shipment verify \
   --shipment /path/to/shipment \
   --traceability \
   --report-json /path/to/shipment/verify_report.json

# Supplier: optionally add metadata into the shipment root
osqar shipment metadata write \
   --shipment examples/python_hello_world/_build/html \
   --name "OSQAr Python Hello World" \
   --version "1.0.0" \
   --url repository=https://example.com/repo.git \
   --origin url=https://example.com/repo.git \
   --origin revision=<commit>

# Integrator: intake multiple shipments and generate a Subproject overview
osqar workspace intake \
   --root intake/received \
   --recursive \
   --output intake/archive/2026-02-01 \
   --traceability

# Optional: enforce declared OSQAr-qualified dependencies
osqar workspace verify \
   --root intake/received \
   --recursive \
   --enforce-deps

# Optional: compute a stable dependency pin for a shipment (SHA256SUMS)
osqar shipment pin --shipment /path/to/shipment

# Generate and open an HTML Subproject overview (via Sphinx)
osqar workspace report \
   --root intake/received \
   --recursive \
   --output intake/overview \
   --open

# Show explicit checksums/traceability status in the HTML overview
osqar workspace report \
   --root intake/received \
   --recursive \
   --output intake/overview \
   --checksums \
   --traceability \
   --open

# Or run the individual shipment steps
osqar build-docs --project examples/python_hello_world
osqar shipment traceability --shipment examples/python_hello_world/_build/html
osqar shipment checksums --shipment examples/python_hello_world/_build/html generate
osqar shipment checksums --shipment examples/python_hello_world/_build/html verify

Then archive and ship the example output directory (not the framework docs built from the repo root).

For multi-project intake patterns, see Multi-project workflows.

Integrator-side procedure (verify a received shipment)¶

Verify the received directory against the provided manifest:

osqar checksum verify \
   --root /path/to/shipment \
   --manifest /path/to/shipment/SHA256SUMS

Optionally re-run the traceability checks on the shipped needs.json:

osqar traceability /path/to/shipment/needs.json \
   --json-report /path/to/shipment/traceability_report.integrator.json

For role-specific guidance (including what to do on mismatches), see:

We also recommend getting familiar with suggestions on overall lifecycle management:

Lifecycle Management

Code complexity (optional)¶

OSQAr supports generating additional engineering evidence artifacts alongside test results.

All reference examples include an optional code complexity report step that produces complexity_report.txt.

C / C++ / Python: lizard (Cyclomatic Complexity)
- Runs as part of the example scripts via poetry run lizard.
- You can run it manually from the repository root, e.g.:
  poetry install --with evidence poetry run lizard -C 10 examples/c_hello_world/src examples/c_hello_world/include
Rust: cargo-cyclo (Cyclomatic Complexity)
- Install once: cargo install cargo-cyclo
- Then run from within the Rust example:
  cd examples/rust_hello_world cargo cyclo

The example scripts treat complexity reporting as best-effort by default (they do not fail the workflow if the tool is not installed). For CI, you can tighten this to enforce thresholds.

Troubleshooting¶

PlantUML in offline environments: set PLANTUML_JAR or install PlantUML locally.
Broken trace links: prefer :need:`ID` references over plain-text IDs.
ID validation failures: keep IDs uppercase with underscores (e.g., REQ_SAFETY_001).

Using the OSQAr Boilerplate¶

What OSQAr Is For¶

How To Use This Guide¶

Quick Start (End-to-End)¶

Recommended reading order¶

Workflow overview¶

Installation options (Poetry groups)¶

Download (optional)¶

Terminology (Project, Shipment, Workspace)¶

Project (shipment project)¶

Shipment directory (built evidence output)¶

Workspace (integrator side)¶

Declared dependencies (pins)¶

Workflow Recipes¶

Build docs (Sphinx HTML)¶

Verify traceability¶

Checksum manifest (shipment integrity)¶

Prepare and verify a shipment (high-level)¶

Reproducible native builds (C / C++ / Rust)¶

Optional: Bazel integration¶

CI-built demo shipments (downloadable)¶

Reference examples¶

Python demo (workstation reference)¶

OSQAr CLI¶

Shell scripts and Windows support¶

Design decision (pragmatic cross-platform support)¶

What this means in practice¶

Support matrix¶

Windows-friendly equivalents (recommended)¶

Scaffold a new project¶

Verify traceability¶

Checksum manifest (shipment integrity)¶

Core authoring workflow¶

Writing requirements (sphinx-needs)¶

Recommended ID scheme¶

Architecture diagrams (PlantUML)¶

Verification and traceability¶

Traceability into source code (“best of both worlds”)¶

Optional CI check: validate IDs in code¶

Shipment verification (per example output)¶

Supplier-side procedure (create the shipment)¶

Integrator-side procedure (verify a received shipment)¶

Code complexity (optional)¶

Troubleshooting¶