osqar 0.5.2__tar.gz

osqar-0.5.2/CHANGELOG.md

@@ -0,0 +1,201 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.5.2] - 2026-02-06
+
+### Added
+- PyPI-distributable OSQAr CLI (`pipx install osqar`) with packaged scaffolding templates.
+
+### Changed
+- `osqar new` now loads templates from packaged resources (works when installed from PyPI; examples are not shipped).
+
+## [0.5.1] - 2026-02-06
+
+### Changed
+- Refactored the OSQAr CLI internals into per-command modules under `tools/` (thin `tools/osqar_cli.py` entrypoint).
+- Removed the previously monolithic `tools/osqar_cli_app/` implementation to improve maintainability.
+
+### Fixed
+- Workspace intake overview now shows project names (instead of a blank Project column).
+
+## [0.5.0] - 2026-02-06
+
+### Added
+- Extensible JSON configuration for projects and workspaces:
+	- `osqar_project.json` supports `commands.docs`, `commands.test`, `commands.build`
+	- `osqar_workspace.json` supports `defaults.exclude` and integrator-side hooks
+- Pre/post hook execution around key CLI events (shipment and workspace workflows)
+- Hook kill switch: `--no-hooks` and environment `OSQAR_DISABLE_HOOKS=1`
+- Integrator-side extra verification commands:
+	- `shipment verify --verify-command '<cmd>'` (repeatable)
+	- `workspace verify --verify-command '<cmd>'` (repeatable)
+- Dedicated documentation page: “Configuration and hooks”
+
+### Changed
+- `build-docs` (top-level shorthand) now also accepts `--config` and `--no-hooks` for parity with `shipment build-docs`
+- Documentation now clarifies the security model: do not execute untrusted commands/hooks from received bundles
+
+## [0.4.2] - 2026-02-06
+
+### Added
+- Workspace HTML overview now follows the main docs theme and includes shared CSS fixes
+
+### Changed
+- Workspace HTML overview renders explicit verification status values for checksums/traceability (OK / FAIL / skipped)
+
+### Fixed
+- Workspace HTML overview no longer appears visually empty in some themes
+- Workspace overview renders placeholders for missing shipment metadata fields (version/origin)
+
+## [0.4.1] - 2026-02-06
+
+### Added
+- `osqar open-docs` convenience command for opening built HTML docs
+- `osqar build-docs --open` to build and open docs in one step
+- Generalized shipment workflows (`shipment prepare`, `shipment verify`) with supplier/integrator commands kept as aliases
+- `osqar doctor` tooling diagnostics (Poetry/Sphinx/PlantUML checks)
+
+### Changed
+- Documentation now consistently prefers `./osqar` shorthand for traceability and checksums
+
+## [0.4.0] - 2026-02-05
+
+### Added
+- Central CLI reference documentation and reduced CLI duplication across guides
+- Cross-platform `osqar` wrapper scripts (`osqar`, `osqar.cmd`, `osqar.ps1`) and a shorthand `build-docs` command
+- Minimal “basic” project templates (C/C++/Rust/Python) with shared template overlays
+- Poetry-managed scaffolds (shared `pyproject.toml` + `poetry.lock`) for fixed documentation/tooling dependencies
+
+### Changed
+- Documentation now prefers `./osqar build-docs` over raw `sphinx-build` invocations
+- `osqar build-docs` prefers running Sphinx inside the target project’s Poetry environment when available
+- Documentation navigation: moved CLI reference and project setup under the Framework section
+
+### Fixed
+- Migrated project metadata to PEP 621 (`[project]`) to avoid Poetry deprecation warnings
+
+## [0.3.1] - 2026-02-03
+
+### Added
+- Embedded JUnit test tables in example documentation (`test-results`), with CI/Pages generating per-example `test_results.xml` before Sphinx builds
+- Embedded per-example code coverage evidence (`coverage_report.txt`) in CI/Pages builds
+- Embedded per-example complexity evidence (`complexity_report.txt`) adjacent to coverage in the shared test results chapter
+
+### Fixed
+- Normalized C/C++/Rust JUnit XML writers to include `errors`, `skipped`, and `time` attributes (prevents `-1` values in rendered summaries)
+
+## [0.3.0] - 2026-02-02
+
+### Added
+- Reproducible native build mode for the C/C++/Rust examples (`OSQAR_REPRODUCIBLE=1` + `SOURCE_DATE_EPOCH`)
+- Optional Bazel integration for the C/C++/Rust examples, including a reproducible `--config=reproducible` mode
+- CI pipeline that builds deterministic example “shipments” (docs + `needs.json` + traceability report + checksums + test report) and uploads them as a downloadable artifact (`osqar-example-shipments`)
+
+### Changed
+- Updated framework documentation and README to advertise reproducible builds and CI demo shipments
+- Reframed OSQAr as a framework for producing, verifying, and integrating auditable evidence shipments
+- Updated Copilot instructions to reflect Poetry-driven Sphinx builds and the shipment workflow
+- CI now builds example shipments in separate jobs (matrix) and combines them afterwards for faster, isolated feedback
+
+### Fixed
+- Fixed a reStructuredText formatting issue in the framework docs that broke the Bazel example code block
+- Fixed Bazel 9 compatibility for the C/C++ examples by explicitly loading `cc_*` rules from `rules_cc`
+- Fixed CI doc builds after Bazel runs by excluding `bazel-*` output trees from Sphinx source discovery (prevents duplicate need IDs)
+- Fixed Bazel wrapper scripts to write JUnit XML to a workspace path (prevents missing `test_results.xml` in CI)
+
+## [0.2.4] - 2026-02-02
+
+### Changed
+- Simplified and restructured the framework documentation entry points to reduce hierarchy and redundancy
+- Removed Markdown boilerplate docs under `docs/` in favor of the published Sphinx documentation
+- Aligned README and framework docs feature descriptions with implemented tooling and configuration
+
+### Added
+- Prominent note that this repository is an example/boilerplate with LLM-assisted/generated content
+
+## [0.2.3] - 2026-02-01
+
+### Added
+- Framework documentation on multi-user collaboration workflows (branching/merging strategies and conflict minimization)
+
+### Fixed
+- Cleaned up and expanded the shared TSIM lifecycle management chapter (removed duplicated content; added practical examples and actions)
+
+## [0.2.2] - 2026-02-01
+
+### Added
+- Integrator multi-project workflow documentation ("Multi-project workflows")
+- Workspace intake/verify tooling for multi-shipment workflows, including a "Subproject overview" (HTML/JSON) with entrypoint links and needs.json-derived counts
+- Optional supplier-provided shipment metadata file (osqar_project.json) with descriptive info, URLs, and origin
+
+## [0.2.1] - 2026-02-01
+
+### Added
+- Shipment-oriented CLI commands to build docs, run tests, clean outputs, collect test reports, generate/verify checksums, and package shipments
+- Unified shipment/workspace workflows for producing and verifying evidence bundles
+- Extensive lifecycle management documentation at framework level and included in each example
+
+## [0.2.0] - 2026-02-01
+
+### Added
+- Complete Temperature Monitor (TSIM) example demonstrating OSQAr capabilities
+- Interactive traceability with 111 clickable requirement links
+- Automated test integration with JUnit XML import
+- PlantUML architecture diagrams with requirement traceability
+- Domain-agnostic thermal sensor interface module (TSIM)
+- Comprehensive test suite with 13 test cases
+- Sphinx documentation with sphinx-needs traceability
+- Poetry-based dependency management
+- GitHub Actions CI/CD template
+- Linked requirement IDs across all documentation
+- Export of machine-readable traceability (`needs.json`) for framework docs and examples
+- Traceability validation tool producing `traceability_report.json`
+- Shipment integrity tool to generate and verify `SHA256SUMS` for example build outputs
+- Supplier/integrator documentation for shipment-style evidence transfer and verification
+- Simple OSQAr CLI (`./osqar` and Windows wrappers `osqar.cmd` / `osqar.ps1`) for scaffolding and verification tasks
+
+### Changed
+- Version bumped to `0.2.0`
+- CI and Pages workflows now run traceability checks and generate checksums for published examples
+- Python compatibility constrained to `<3.14` due to upstream dependency support
+
+### Fixed
+- Root docs build no longer indexes `.venv` contents when building locally
+
+### Changed
+- Enhanced traceability matrix with clickable links
+- Improved documentation structure with cross-references
+
+### Fixed
+- PlantUML rendering compatibility issues
+- Python version compatibility (3.11+)
+
+## [0.1.0] - 2026-01-23
+
+### Added
+- Initial release of OSQAr (Open Safety Qualification Architecture)
+- Core Sphinx configuration with sphinx-needs
+- Basic documentation boilerplate
+- Poetry project setup
+- Apache-2.0 License
+
+### Changed
+- N/A (initial release)
+
+### Deprecated
+- N/A (initial release)
+
+### Removed
+- N/A (initial release)
+
+### Fixed
+- N/A (initial release)
+
+### Security
+- N/A (initial release)

osqar-0.5.2/LICENSE

@@ -0,0 +1,158 @@
+Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+   "License" shall mean the terms and conditions for use, reproduction,
+   and distribution as defined by Sections 1 through 9 of this document.
+
+2. Grant of Copyright License. Subject to the terms and conditions of
+   this License, each contributor hereby grants to You a perpetual,
+   worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+   copyright license to reproduce, prepare Derivative Works of,
+   publicly display, publicly perform, sublicense, and distribute the
+   Work and such Derivative Works in Source or Object form.
+
+3. Grant of Patent License. Subject to the terms and conditions of
+   this License, each contributor hereby grants to You a perpetual,
+   worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+   (except as stated in this section) patent license to make, have
+   made, use, offer to sell, sell, import, and otherwise transfer the
+   Work, where such license applies only to those patent claims
+   licensable by such contributor that are necessarily infringed by
+   their Contribution(s) alone or by combination of their
+   Contribution(s) with the Work to which such Contribution(s)
+   was submitted. If You institute patent litigation against any
+   entity (including a cross-claim or counterclaim in a lawsuit)
+   alleging that the Work or a Contribution incorporated within the
+   Work constitutes direct or contributory patent infringement,
+   then any patent licenses granted to You under this License for
+   that Work shall terminate as of the date such litigation is filed.
+
+4. Redistribution. You may reproduce and distribute copies of the
+   Work or Derivative Works thereof in any medium, with or without
+   modifications, and in Source or Object form, provided that You
+   meet the following conditions:
+
+   (a) You must give any other recipients of the Work or
+       Derivative Works a copy of this License; and
+
+   (b) You must cause any modified files to carry prominent notices
+       stating that You changed the files; and
+
+   (c) You must retain, in the Source form of any Derivative Works
+       that You distribute, all copyright, patent, trademark, and
+       attribution notices from the Source form of the Work,
+       excluding those notices that do not pertain to any part of
+       the Derivative Works; and
+
+   (d) If the Work includes a "NOTICE" text file as part of its
+       distribution, then any Derivative Works that You distribute must
+       include a readable copy of the attribution notices contained
+       within such NOTICE file, excluding those notices that do not
+       pertain to any part of the Derivative Works, in at least one
+       of the following places: within a NOTICE text file distributed
+       as part of the Derivative Works; within the Source form or
+       documentation; or within a display generated by the Derivative
+       Works, provided that any such attribution notices do not
+       modify the license terms and conditions of this License.
+
+   You may add Your own attribution notices within Derivative Works
+   that You distribute, alongside or as an addendum to the NOTICE
+   text from the Work, provided that such additional attribution
+   notices cannot be construed as modifying the License.
+
+5. Submission of Contributions. Unless You explicitly state otherwise,
+   any Contribution intentionally submitted for inclusion in the Work
+   by You to the Licensor shall be under the terms and conditions of
+   this License, without any additional terms or conditions.
+   Notwithstanding the above, nothing herein shall supersede or modify
+   the terms of any separate license agreement you may have executed
+   with Licensor regarding such Contributions.
+
+6. Trademarks. This License does not grant permission to use the trade
+   names, trademarks, service marks, or product names of the Licensor,
+   except as required for reasonable and customary use in describing the
+   origin of the Work and reproducing the content of the NOTICE file.
+
+7. Disclaimer of Warranty. Unless required by applicable law or
+   agreed to in writing, Licensor provides the Work (and each
+   Contributor provides its Contributions) on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+   implied, including, without limitation, any warranties or
+   conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or
+   FITNESS FOR A PARTICULAR PURPOSE.
+
+8. Limitation of Liability. In no event and under no legal theory,
+   whether in tort (including negligence), contract, or otherwise,
+   unless required by applicable law (such as deliberate and grossly
+   negligent acts) or agreed to in writing, shall any Contributor be
+   liable to You for damages, including any direct, indirect,
+   special, incidental, or consequential damages of any character
+   arising as a result of this License or out of the use or inability
+   to use the Work (including but not limited to damages for loss of
+   goodwill, work stoppage, computer failure or malfunction, or any
+   and all other commercial damages or losses), even if such
+   Contributor has been advised of the possibility of such damages.
+
+9. Accepting Warranty or Additional Liability. While redistributing
+   the Work or Derivative Works thereof, You may choose to offer,
+   and charge a fee for, acceptance of support, warranty, indemnity,
+   or other liability obligations and/or rights consistent with this
+   License. However, in accepting such obligations, You may act only
+   on Your own behalf and on Your sole responsibility, not on behalf
+   of any other Contributor, and only if You agree to indemnify,
+   defend, and hold each Contributor harmless for any liability
+   incurred by, or claims asserted against, such Contributor by reason
+   of your accepting any such warranty or additional liability.
+
+END OF TERMS AND CONDITIONS
+
+APPENDIX: How to apply the Apache License to your work.
+
+   To apply the Apache License to your work, attach the following
+   boilerplate notice, with the fields enclosed by brackets "[]"
+   replaced with your own identifying information. (Don't include
+   the brackets!)  The text should be enclosed in the appropriate
+   comment syntax for the file format. We also recommend that a
+   file or class name and description of purpose be included on the
+   same "printed page" as the copyright notice for easier
+   identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+   implied. See the License for the specific language governing
+   permissions and limitations under the License.
+MIT License
+
+Copyright (c) 2026 OSQAr Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

osqar-0.5.2/MANIFEST.in

@@ -0,0 +1,15 @@
+include README.md
+include CHANGELOG.md
+include LICENSE
+include NOTICE
+
+# Ship packaged resources
+recursive-include osqar_data/templates *
+recursive-include osqar_data/static *
+
+# Avoid shipping large/non-release directories
+prune _build
+prune examples
+prune __pycache__
+recursive-exclude * __pycache__
+recursive-exclude * *.pyc

osqar-0.5.2/NOTICE

@@ -0,0 +1,10 @@
+OSQAr - Open Safety Qualification Architecture
+
+Copyright 2026 Jan Toennemann
+
+This product is licensed under the Apache License, Version 2.0.
+See the `LICENSE` file for the full license text and conditions.
+
+Third-party notices:
+- This project depends on several open-source libraries (see `pyproject.toml`).
+- No separate third-party NOTICE entries are included at this time.

osqar-0.5.2/PKG-INFO

@@ -0,0 +1,156 @@
+Metadata-Version: 2.4
+Name: osqar
+Version: 0.5.2
+Summary: Open Safety Qualification Architecture - A Sphinx-Needs boilerplate for safety-related systems.
+Author-email: Jan Toennemann <jan@toennemann.net>
+License-Expression: Apache-2.0
+Requires-Python: <3.15,>=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: NOTICE
+Requires-Dist: Sphinx==7.2.*
+Requires-Dist: sphinx-needs>=2.0
+Requires-Dist: sphinx-test-reports>=1.0
+Requires-Dist: sphinxcontrib-plantuml>=0.25
+Requires-Dist: furo>=2024.8.6
+Dynamic: license-file
+
+[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
+[![CI (Tests and Builds)](https://github.com/bitvortex/OSQAr/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/bitvortex/OSQAr/actions/workflows/ci.yml)
+[![Docs (GitHub Pages)](https://github.com/bitvortex/OSQAr/actions/workflows/pages-deploy.yml/badge.svg?branch=main)](https://github.com/bitvortex/OSQAr/actions/workflows/pages-deploy.yml)
+
+# OSQAr
+
+Open Safety Qualification Architecture (OSQAr) is a documentation-first framework for producing and integrating **auditable evidence shipments** for safety/compliance work.
+
+A shipment is a reviewable bundle that contains **Sphinx documentation with maintained traceability**, plus the **implementation**, **tests**, and **analysis/verification reports** needed to audit the evidence end-to-end.
+
+## Who this is for
+
+OSQAr is for teams that need **auditable, reviewable engineering evidence** with traceability (requirements ↔ architecture ↔ verification), especially when evidence must be transferred between organizations.
+
+Typical roles and workflows:
+
+- **Suppliers**: build docs and verification evidence, then prepare integrity-protected shipments (HTML + `needs.json` + reports + `SHA256SUMS`).
+- **Integrators**: verify received shipments (checksums, optional traceability re-check), run extra integrator-side checks, and archive multiple shipments into a single intake with a consolidated HTML overview.
+- **Internal teams**: use the same shipment workflow to standardize evidence packaging across subprojects and CI.
+
+## Features / use cases
+
+- Write structured requirements, architecture and verification plans in reStructuredText (traceability via `sphinx-needs`)
+- Render architecture diagrams with PlantUML (embedded in the docs)
+- Export machine-readable traceability (`needs.json`) alongside HTML
+- Generate traceability views (e.g., matrices) and keep verification coverage reviewable
+- Verify traceability rules and produce audit-friendly reports
+- Trace requirements, architecture and tests into the actual code and check for consistency
+- Package documentation + evidence artifacts and protect them with checksum manifests
+- Integrate multiple shipments in a workspace and review a consolidated overview
+- Extend workflows via project and workspace configuration (custom commands + hooks)
+- Use lifecycle management and collaboration workflows for multi-user teams
+- Run reproducible native builds for the C/C++/Rust reference examples with optional Bazel integration
+- Use CI-produced demo shipments and downloadable release bundles as a starting point for your own project setup, or scaffold new projects from minimal templates (C/C++/Rust/Python) via the OSQAr CLI
+
+## Docs and examples
+
+- Framework docs (published): https://bitvortex.github.io/OSQAr/
+- Examples index (published): https://bitvortex.github.io/OSQAr/examples/
+- Download pre-built bundles (framework bundle, example workspace): https://github.com/bitvortex/OSQAr/releases
+
+## Quickstart
+
+Dependencies:
+
+- Python `>=3.9` (see `pyproject.toml`)
+- Poetry: https://python-poetry.org/
+- Optional for offline PlantUML rendering: Java and/or PlantUML (`PLANTUML_JAR` also works). If neither is available, the build falls back to the public PlantUML web service (requires internet).
+
+Install the OSQAr CLI (recommended for users):
+
+```bash
+pipx install osqar
+osqar --help
+```
+
+Notes:
+
+- The PyPI package includes the **minimal project templates** used by `osqar new`.
+- The full reference `examples/` are not shipped on PyPI; use the git repo or release bundles if you need them.
+
+Build the framework documentation (repo root):
+
+```bash
+poetry install
+./osqar build-docs
+./osqar open-docs
+```
+
+Build an example’s documentation (choose one):
+
+```bash
+./osqar build-docs --project examples/c_hello_world
+./osqar build-docs --project examples/cpp_hello_world
+./osqar build-docs --project examples/rust_hello_world
+./osqar build-docs --project examples/python_hello_world
+```
+
+Run an example end-to-end (tests → docs), including optional evidence tooling:
+
+```bash
+poetry install --with evidence
+cd examples/c_hello_world
+./build-and-test.sh
+```
+
+Create a new project (minimal template scaffold):
+
+```bash
+# Default template profile is "basic" (lean scaffold)
+./osqar new --language c --name MySEooC --destination ../MySEooC
+```
+
+Notes:
+
+- The `./osqar` wrapper is intended to be run from the OSQAr repo root.
+- On Windows, use `osqar.cmd` or `osqar.ps1` from the repo root.
+
+## Extensibility (custom commands + hooks)
+
+OSQAr supports optional JSON configuration files so teams can plug in their own build/test/verification tooling while keeping OSQAr’s evidence structure, traceability, and integrity checks.
+
+Project-side config: `osqar_project.json`
+
+- Put this file in a project root (supplier/dev side).
+- Use `commands.test` and `commands.docs` to override how tests and docs are executed.
+- Use `hooks.pre` / `hooks.post` to run pre/post actions around OSQAr command events.
+
+Example:
+
+```json
+{
+
+  "commands": {
+    "test": "OSQAR_REPRODUCIBLE=1 ./build-and-test.sh",
+    "docs": "poetry run sphinx-build -b html . _build/html"
+  },
+  "hooks": {
+    "pre": {
+      "shipment.prepare": "echo pre-prepare"
+    },
+    "post": {
+      "shipment.prepare": ["echo post-prepare", "echo done"]
+    }
+  }
+}
+```
+
+Integrator-side config: `osqar_workspace.json`
+
+- Put this file in a trusted integrator workspace root and use it with `workspace report/verify/intake`.
+- You can also attach extra integrator-side checks to shipment verification via `--verify-command` (repeatable).
+- For `shipment verify`, use `--config-root <trusted_dir>` to load workspace config from a trusted location.
+
+Hook kill switch:
+
+- Set `OSQAR_DISABLE_HOOKS=1` or pass `--no-hooks`.
+
+See the published docs for the full reference (supported keys, hook events, and security notes).

osqar-0.5.2/README.md

@@ -0,0 +1,139 @@
+[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
+[![CI (Tests and Builds)](https://github.com/bitvortex/OSQAr/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/bitvortex/OSQAr/actions/workflows/ci.yml)
+[![Docs (GitHub Pages)](https://github.com/bitvortex/OSQAr/actions/workflows/pages-deploy.yml/badge.svg?branch=main)](https://github.com/bitvortex/OSQAr/actions/workflows/pages-deploy.yml)
+
+# OSQAr
+
+Open Safety Qualification Architecture (OSQAr) is a documentation-first framework for producing and integrating **auditable evidence shipments** for safety/compliance work.
+
+A shipment is a reviewable bundle that contains **Sphinx documentation with maintained traceability**, plus the **implementation**, **tests**, and **analysis/verification reports** needed to audit the evidence end-to-end.
+
+## Who this is for
+
+OSQAr is for teams that need **auditable, reviewable engineering evidence** with traceability (requirements ↔ architecture ↔ verification), especially when evidence must be transferred between organizations.
+
+Typical roles and workflows:
+
+- **Suppliers**: build docs and verification evidence, then prepare integrity-protected shipments (HTML + `needs.json` + reports + `SHA256SUMS`).
+- **Integrators**: verify received shipments (checksums, optional traceability re-check), run extra integrator-side checks, and archive multiple shipments into a single intake with a consolidated HTML overview.
+- **Internal teams**: use the same shipment workflow to standardize evidence packaging across subprojects and CI.
+
+## Features / use cases
+
+- Write structured requirements, architecture and verification plans in reStructuredText (traceability via `sphinx-needs`)
+- Render architecture diagrams with PlantUML (embedded in the docs)
+- Export machine-readable traceability (`needs.json`) alongside HTML
+- Generate traceability views (e.g., matrices) and keep verification coverage reviewable
+- Verify traceability rules and produce audit-friendly reports
+- Trace requirements, architecture and tests into the actual code and check for consistency
+- Package documentation + evidence artifacts and protect them with checksum manifests
+- Integrate multiple shipments in a workspace and review a consolidated overview
+- Extend workflows via project and workspace configuration (custom commands + hooks)
+- Use lifecycle management and collaboration workflows for multi-user teams
+- Run reproducible native builds for the C/C++/Rust reference examples with optional Bazel integration
+- Use CI-produced demo shipments and downloadable release bundles as a starting point for your own project setup, or scaffold new projects from minimal templates (C/C++/Rust/Python) via the OSQAr CLI
+
+## Docs and examples
+
+- Framework docs (published): https://bitvortex.github.io/OSQAr/
+- Examples index (published): https://bitvortex.github.io/OSQAr/examples/
+- Download pre-built bundles (framework bundle, example workspace): https://github.com/bitvortex/OSQAr/releases
+
+## Quickstart
+
+Dependencies:
+
+- Python `>=3.9` (see `pyproject.toml`)
+- Poetry: https://python-poetry.org/
+- Optional for offline PlantUML rendering: Java and/or PlantUML (`PLANTUML_JAR` also works). If neither is available, the build falls back to the public PlantUML web service (requires internet).
+
+Install the OSQAr CLI (recommended for users):
+
+```bash
+pipx install osqar
+osqar --help
+```
+
+Notes:
+
+- The PyPI package includes the **minimal project templates** used by `osqar new`.
+- The full reference `examples/` are not shipped on PyPI; use the git repo or release bundles if you need them.
+
+Build the framework documentation (repo root):
+
+```bash
+poetry install
+./osqar build-docs
+./osqar open-docs
+```
+
+Build an example’s documentation (choose one):
+
+```bash
+./osqar build-docs --project examples/c_hello_world
+./osqar build-docs --project examples/cpp_hello_world
+./osqar build-docs --project examples/rust_hello_world
+./osqar build-docs --project examples/python_hello_world
+```
+
+Run an example end-to-end (tests → docs), including optional evidence tooling:
+
+```bash
+poetry install --with evidence
+cd examples/c_hello_world
+./build-and-test.sh
+```
+
+Create a new project (minimal template scaffold):
+
+```bash
+# Default template profile is "basic" (lean scaffold)
+./osqar new --language c --name MySEooC --destination ../MySEooC
+```
+
+Notes:
+
+- The `./osqar` wrapper is intended to be run from the OSQAr repo root.
+- On Windows, use `osqar.cmd` or `osqar.ps1` from the repo root.
+
+## Extensibility (custom commands + hooks)
+
+OSQAr supports optional JSON configuration files so teams can plug in their own build/test/verification tooling while keeping OSQAr’s evidence structure, traceability, and integrity checks.
+
+Project-side config: `osqar_project.json`
+
+- Put this file in a project root (supplier/dev side).
+- Use `commands.test` and `commands.docs` to override how tests and docs are executed.
+- Use `hooks.pre` / `hooks.post` to run pre/post actions around OSQAr command events.
+
+Example:
+
+```json
+{
+
+  "commands": {
+    "test": "OSQAR_REPRODUCIBLE=1 ./build-and-test.sh",
+    "docs": "poetry run sphinx-build -b html . _build/html"
+  },
+  "hooks": {
+    "pre": {
+      "shipment.prepare": "echo pre-prepare"
+    },
+    "post": {
+      "shipment.prepare": ["echo post-prepare", "echo done"]
+    }
+  }
+}
+```
+
+Integrator-side config: `osqar_workspace.json`
+
+- Put this file in a trusted integrator workspace root and use it with `workspace report/verify/intake`.
+- You can also attach extra integrator-side checks to shipment verification via `--verify-command` (repeatable).
+- For `shipment verify`, use `--config-root <trusted_dir>` to load workspace config from a trusted location.
+
+Hook kill switch:
+
+- Set `OSQAR_DISABLE_HOOKS=1` or pass `--no-hooks`.
+
+See the published docs for the full reference (supported keys, hook events, and security notes).