Multi-project workflows

This section describes how to work with multiple supplier projects/shipments at once. The goal is to keep evidence intake scalable and repeatable, while preserving integrity and traceability.

Quick start (integrator)

This is the simplest repeatable workflow when you receive multiple shipments:

# 1) Put supplier shipments under intake/received/<name>/
# 2) Verify + archive them into a dated intake folder
osqar workspace intake \
  --root intake/received \
  --recursive \
  --output intake/archive/2026-02-01 \
  --traceability

Then open the generated overview:

open intake/archive/2026-02-01/_build/html/index.html

Concepts

Project

A Sphinx documentation project that contains at least conf.py and index.rst.

Shipment

A directory that a supplier provides to an integrator as an evidence bundle. In OSQAr, a shipment is an evidence bundle that contains Sphinx documentation with maintained traceability, plus implementation sources, tests, and analysis/verification reports.

Common bundle contents include:

• Documentation (rendered HTML)

• needs.json (exported by sphinx-needs)

• SHA256SUMS (integrity manifest)

• traceability_report.json (recommended)

• Raw test reports (e.g. JUnit XML)

• Coverage/analysis reports (e.g. coverage summary, complexity report)

• Implementation sources and tests (so evidence can be reviewed end-to-end)

Recommended folder layout (integrator)

Keep supplier inputs immutable and separate from your integrator-side processing. A simple layout that works well for multi-project intake:

intake/
received/              # immutable: supplier-provided shipments
archive/               # immutable: your frozen intake archive(s)
working/               # mutable: scratch, analysis, combined views
reports/               # integrator-side summaries (JSON/CSV/etc)

Typical process

1. Receive shipments into received/ (do not modify them).

2. Verify integrity (checksums) before any further processing.

3. Optionally run an integrator-side traceability check.

4. Copy verified shipments into a dated archive and write an intake report.

5. Build combined views (indexes, dashboards, consolidated evidence) from the archive.

What the intake produces

An intake directory is meant to be self-contained and audit-friendly:

 intake/archive/2026-02-01/
   intake_report.json
   subproject_overview.json
   SHA256SUMS
   _build/
     html/
       index.html
   shipments/
     <shipment-name>/
       index.html
       needs.json
       osqar_project.json
       ... (rendered docs and shipped artifacts)
  reports/
     <shipment-name>/
       traceability_report.integrator.json
       doctor_report.integrator.json

The file ``_build/html/index.html`` is intended as the main human entrypoint.

Batch verification (CLI)

To verify many shipments at once (integrator side), use the workspace commands. They discover shipment directories by scanning for SHA256SUMS.

# Verify all shipments under a folder
osqar workspace verify \
  --root intake/received \
  --recursive

# Also run traceability checks (writes integrator-side reports alongside your archive/intake output)
osqar workspace verify \
  --root intake/received \
  --recursive \
  --traceability

Optional: workspace configuration

If you want team-wide defaults (e.g., checksum exclude globs) or integrator-side hooks around workspace operations, place an osqar_workspace.json in a trusted workspace root and pass it via --config.

For example:

osqar workspace verify --root intake/received --recursive --config osqar_workspace.json

See Configuration and hooks for details.

Intake + archiving (CLI)

To create an immutable intake archive from multiple shipments:

osqar workspace intake \
   --root intake/received \
   --recursive \
   --output intake/archive/2026-02-01 \
   --traceability \
   --doctor

The intake output is structured so that the copied shipments remain byte-identical, while integrator-side reports are written separately.

Practical naming convention

To keep multi-project work manageable, ensure shipment folders are unique and human-readable. Good patterns:

• <supplier>_<component>_<version>

• <supplier>_<component>_<version>_<platform>

Avoid ambiguous names like shipment/ or output/.

Shipment metadata (supplier)

Suppliers can include a machine-readable metadata file in the shipment root:

• osqar_project.json

This can contain descriptive metadata as well as URLs (repository, homepage, documentation) and an explicit origin (e.g., VCS URL + revision). Integrators can use this to record where a shipment came from and how it maps back to source control.

Write metadata into a shipment directory:

osqar shipment metadata write \
   --shipment <bundle_dir> \
   --name "My Component" \
   --version "1.2.3" \
   --description "Safety element out of context (SEooC)" \
   --url repository=https://example.com/repo.git \
   --url documentation=https://example.com/docs \
   --origin url=https://example.com/repo.git \
   --origin revision=abc123

Shipment dependencies (supplier)

If an OSQAr-qualified library depends on other OSQAr-qualified libraries, declare these dependencies in the shipped osqar_project.json.

Recommended structure:

{
  "schema": "osqar.shipment_project_metadata.v1",
  "id": "LIB_CONSUMER",
  "version": "1.2.3",
  "dependencies": [
    {
      "id": "LIB_PROVIDER",
      "version": "2.0.0",
      "pin_sha256sums": "<sha256-of-SHA256SUMS-file-bytes>"
    }
  ]
}

The pin_sha256sums field is a stable identifier of the dependency shipment’s SHA256SUMS manifest file.

Compute a dependency pin from a received or built shipment directory:

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

Subproject overview (integrator output)

When you run an intake, OSQAr generates a Subproject overview in the intake output:

• subproject_overview.json

• _build/html/index.html

These summarize all projects/shipments, their verification status, and (if present) their supplier-provided metadata (including origin and URLs).

The overview additionally includes:

• A link to the archived HTML entrypoint (shipments/<name>/index.html), if present

• A small needs export summary derived from needs.json (total needs, REQ/ARCH/TEST counts)

If a supplier does not provide osqar_project.json, the overview still works, but it will have less context about origin/URLs.

Notes and good practices

• Verify SHA256SUMS before running any analysis tools.

• Do not regenerate supplier manifests; verify them.

• Keep integrator-generated artifacts (reports, dashboards) outside the shipment tree.

• Prefer deterministic naming (supplier, component, version) for shipment folders.

Workspace dependency enforcement (integrator)

Workspace commands can validate declared dependencies across all shipments:

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

With --enforce-deps, OSQAr fails the command if dependencies are missing, ambiguous, or conflicting (for example, the same dependency id is requested with different versions or pins in the same workspace).

How to observe deduplication

After running osqar workspace intake or osqar workspace report, you can observe logical deduplication in two places:

• In the generated HTML overview, the summary line includes shared_satisfiers=<N>. This counts how many distinct dependency shipments satisfy more than one dependent project.

• In the JSON overview (written as subproject_overview.json in the output directory), look at dependency_analysis.summary.shared_satisfiers_total and the dependency_analysis.resolutions list (each entry records dependency.satisfied_by).

If your workspace contains identical duplicate shipments (same id/version/pin present multiple times), those are reported separately as dedup_groups=<N> and in dependency_analysis.dedup.