> ## Documentation Index
> Fetch the complete documentation index at: https://docs.roboticks.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Release Scoping

> A pack is scoped to a Release (pinned commits across every linked repo plus a requirements snapshot) or to a branch + commit set for ad-hoc inspection.

# Release Scoping

An evidence pack belongs to either a **Release** or an ad-hoc **`branch + commit_set`**. The Release form is what auditors expect; the ad-hoc form exists for debugging, customer escalations, and sandbox runs.

## Releases — the canonical form

A Release in Roboticks is an immutable pinning of:

* A specific commit on every linked repository.
* A snapshot of every requirement at the moment the Release was cut.
* The verification results — every test run that fed verification, every MCAP, every coverage report.
* A reference to the pinned [standards](/standards/pinning) and their edition / amendment level at cut time.

Once a Release reaches state `verified`, none of the above can change. Re-verifying a Release is a **pure replay**: the platform re-runs the same tests on the same commit set; the outcomes are added to the Release's verification history without altering the original. Auditors see the full re-verification history alongside the original results.

### The Release state machine

```mermaid theme={null}
%%{init: {"theme": "neutral", "themeVariables": {"primaryColor": "#4040ff"}} }%%
stateDiagram-v2
    [*] --> draft
    draft --> verifying : Cut release
    verifying --> verified : All required tests pass
    verifying --> draft : Failures, fix and re-cut
    verified --> shipped : Mark as shipped
    shipped --> archived : Beyond active support
    verified --> verifying : Re-verify (pure replay)
    shipped --> verifying : Re-verify (pure replay)
```

| State       | What it means                                                    | Pack generation                   |
| ----------- | ---------------------------------------------------------------- | --------------------------------- |
| `draft`     | Release exists, commits pinned, but verification has not started | Not allowed                       |
| `verifying` | Tests are running against the pinned commit set                  | Not allowed                       |
| `verified`  | Every required test passed; the Release is ready to ship         | **Allowed**                       |
| `shipped`   | Marked as released to customers; appears in posture dashboards   | **Allowed**                       |
| `archived`  | Beyond active support; evidence in Deep Archive                  | Allowed; requires Glacier restore |

A pack generated against a `verified` Release is identical to one generated against the same Release after it transitions to `shipped`. The transition is metadata; it does not alter evidence.

### Cutting a Release

<Steps>
  <Step title="Create the Release">
    From the dashboard: **Releases → Cut new release**. Or from CLI: `rbtk release cut --tag v1.4.0`. Provide a tag, a title, and the commits to pin (one per linked repository — defaults to the most recent commit on the chosen branch).
  </Step>

  <Step title="Snapshot requirements">
    The platform automatically snapshots every pinned requirement. This is a deep copy — the snapshot is immutable even if the live requirement is later edited.
  </Step>

  <Step title="Run verification">
    The platform dispatches every required test to the runner pools. Status moves from `draft` → `verifying`.
  </Step>

  <Step title="Reach verified">
    On full pass, the Release auto-promotes to `verified`. On any required failure, it returns to `draft` for fix-and-recut. (Optional acknowledged-gap workflow lets you promote with documented gaps; the pack records the acknowledgment.)
  </Step>

  <Step title="Generate the pack">
    See [Generation](/evidence/generation).
  </Step>

  <Step title="Mark as shipped">
    When you actually ship the build to customers, mark the Release `shipped`. This is the trigger that starts the 10-year retention clock.
  </Step>
</Steps>

### Re-verification semantics

A Release can be re-verified at any time. Re-verification is intentionally constrained:

* The exact pinned commits are checked out — no `latest` substitution.
* The same requirement snapshot is in force.
* The same test selection runs.
* The original results are retained; the re-verification adds a new run alongside.

This is what powers [Re-conformity on amendment](/compliance/re-conformity-on-amendment): when a pinned standard amends, you re-verify the affected Releases against the same commits to demonstrate continued conformance — or to surface the specific tests that now fail against the new clause.

## Ad-hoc commit sets

For investigations that do not correspond to a shipped Release — bisecting a regression, evaluating a customer-reported failure on a specific commit, exploring "would this hypothetical patch pass" — generate a pack scoped to a `branch + commit_set`:

```bash theme={null}
rbtk test evidence-pack \
  --branch fix/imu-drift \
  --commit-set 9b14ab8 \
  --format zip
```

The pack:

* Is fully signed, enters the [hash chain](/evidence/hash-chain), and is retained per the project's retention policy.
* Is **watermarked NOT FOR RELEASE** in the PDF.
* Does not appear in the posture dashboard or in conformance rolls.
* Is suitable for engineering forensics, customer support evidence, and internal QA, but not for regulator hand-off.

The watermark is intentional: an auditor seeing a `NOT FOR RELEASE` pack should reject it. The scoping protects you from accidentally handing an ad-hoc inspection to an external party as if it were a release artefact.

## Which to use

| Scenario                                                                       | Scope             |
| ------------------------------------------------------------------------------ | ----------------- |
| Shipping a build to customers                                                  | Release           |
| Submitting evidence to a notified body                                         | Release           |
| Customer asks "what does the May 2026 build look like under ISO 10218-1:2025?" | Release           |
| Bisecting a flaky test across 8 commits                                        | Ad-hoc per commit |
| Producing evidence for an internal change-control board on an in-flight branch | Ad-hoc            |
| Demonstrating that a proposed patch fixes a regression                         | Ad-hoc            |

## Multi-repository releases

Most production robotics codebases span multiple repositories — firmware, messages, simulation worlds, deploy tooling. A Roboticks Release pins commits across all of them via the **project's linked repositories** configuration.

When you cut a Release, the dashboard shows every linked repository and lets you pick the commit (or branch HEAD) for each. The pack records all of them in `release.repositories`.

## Next steps

<CardGroup cols={2}>
  <Card title="Generate a pack" icon="file-export" href="/evidence/generation">
    From a Release or an ad-hoc commit set.
  </Card>

  <Card title="Re-conformity workflow" icon="rotate" href="/compliance/re-conformity-on-amendment">
    Re-verifying a Release after a standard amends.
  </Card>

  <Card title="Internal release gate" icon="gauge" href="/compliance/internal-release-gate">
    Using Releases as your internal QA gate.
  </Card>
</CardGroup>