Skip to main content

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.

​
Snapshotting

The single property that makes Roboticks audit-grade is this: when you cut a release, the requirement set for that release is frozen. Three years later, when an auditor opens the evidence pack, they see exactly what you verified against — not a drifted-since version, not “what the team meant to verify”. The snapshot is the truth.
A snapshot is immutable. Edits after a snapshot create a new version of the requirement. The snapshot keeps pointing at the version that existed at snapshot time, forever.

​
When a snapshot is created

A snapshot is created when:
TriggerWhat is snapshotted
You cut a release in Roboticks (rbtk release create v1.2.0 or the dashboard equivalent)The current state of every requirement, every link, and every verification result on the chosen SHA.
A scheduled rollup runs (optional, per-project, default off)Same as above, on a fixed cadence. Useful for monthly audit-ready packs without an explicit release.
The SDK calls client.snapshots.create(...) from a custom scriptSame.
There is no automatic snapshot on every push. Snapshots are deliberate, named events that produce an evidence pack.

​
What goes into a snapshot

Every artifact carries the snapshot ID. Browsing the matrix in “snapshot v1.2.0” mode shows you the world as it was at snapshot time, not the live state.

​
Editing a snapshotted requirement

You can edit any requirement at any time. What happens to a snapshotted one:
  1. The edit creates a new version of the requirement. The version number increments (e.g. REQ-014@v3 → REQ-014@v4).
  2. The snapshot keeps pointing at the old version. v1.2.0 still verifies against REQ-014@v3.
  3. The live state moves to REQ-014@v4. The next snapshot will pick up v4.
  4. The audit trail records the diff (field-level), the author, the timestamp, and the linked release(s) affected.
This is how Roboticks reconciles two things auditors care about:
  • Stability. A release once shipped does not change.
  • Evolution. Requirements get tightened, clarified, and added as the product matures.

​
Deleting a snapshotted requirement

You can’t truly delete a snapshotted requirement — the snapshot needs it. What you can do:
  • Mark as obsolete in the live state. Future snapshots won’t include it. Past snapshots still do.
  • Hard-delete from the live state. Permitted only if the requirement is not in any snapshot. Once snapshotted, it’s around for the snapshot’s retention life.

​
Snapshot retention

TierSnapshot retention
Free90 days
Team10 years (EU Product Liability tail)
Enterprise10 years (Glacier Deep Archive, retrievable on demand)
The evidence pack PDF / ReqIF / ZIP for each snapshot is tamper-evident — every file’s SHA-256 is chained into the next, and the chain head is signed. See Evidence pack.

​
The audit trail

Every edit on a requirement — pre- or post-snapshot — is appended to the requirement’s audit trail. Each entry records:
  • The full pre/post state of every field that changed.
  • The author (GitHub user or Roboticks dashboard user).
  • The timestamp (server-side UTC).
  • The originating action (web edit, ReqIF re-import, SDK call, etc.).
  • The releases affected (which snapshots reference the prior version).
The audit trail is append-only. It is exported with the evidence pack and signed in the same hash chain. Auditors expect this; we make it the default. 
{
  "requirement_id": "REQ-014",
  "version_from": 3,
  "version_to": 4,
  "author": "alice@acme.io",
  "ts": "2026-05-14T09:12:33Z",
  "action": "web_edit",
  "diff": [
    {"field": "text", "from": "...within 100 ms...", "to": "...within 80 ms..."},
    {"field": "title", "from": "...100 ms", "to": "...80 ms"}
  ],
  "snapshots_affected": ["v1.2.0"]
}

​
Snapshots vs Git tags

A Roboticks snapshot is not a Git tag. They overlap — a snapshot is usually tied to a SHA that is also tagged in Git — but the snapshot captures more than the commit:
Git tagRoboticks snapshot
Source code state✓✓ (via SHA pointer)
Test results✗✓
Requirement set✗✓ (frozen)
Verification status per requirement✗✓
Audit trail of who changed what when✗✓
Tamper-evident hash chain✗✓
Retention policyRepo-managedTier-bound, 10 yr on Team / Enterprise
You can cross-reference: a Git tag has an associated snapshot ID; a snapshot points at the SHA + tag.

​
Branching: long-lived release branches

Long-lived release branches (e.g. release/v1.x) generate their own snapshot lineage. The snapshot for v1.2.0 is independent of v1.3.0, which is independent of v2.0.0. Each lineage has its own audit trail and its own evidence packs. This matches the way regulated teams ship — v1.x keeps getting safety patches for years after v2.0 lands; each v1.x.y patch needs its own audit-grade evidence pack against the requirements as they stood for that lineage.

​
Re-running tests against an old snapshot

Sometimes you need to re-run the tests as they existed at a snapshot — for example, to investigate a regression report from the field. The CLI: 
rbtk snapshots replay v1.2.0
This dispatches a fresh test run on a runner using the SHA from the snapshot, the same runner image tag, and the same test command. Results are written to a re-verification record on the snapshot — the original results stay untouched.

​
Next

Evidence pack

The PDF / ReqIF / ZIP a snapshot generates.

Hierarchy

How tree shape interacts with snapshots.

Coverage

Snapshot vs live coverage states.

CLI release commands

rbtk release and rbtk snapshots.