Provenance

Never lose the why behind your decisions.

Provenance is a tool for building requirements traceability, from source to requirement to rule. A Rule is an atomic behavioural obligation that can exist before its implementation; #[rule("rule_id")] binds production code to it, and #[verifies("rule_id", method)] binds evidence.

Installation

Install and initialize Provenance in a TypeScript project:

npx --yes @quality-sh/create-provenance

The initializer detects npm, pnpm, Yarn, Bun, Deno, or Nub. It installs @quality-sh/provenance as an exact development dependency, creates the default scope, validates the state, and ignores .provenance/cache/.

Install and initialize Provenance in an existing Rust project:

cargo install provenance-cli
cargo provenance init

The Cargo initializer finds the current workspace, adds provenance-sdk at the CLI version, creates the default scope, validates the state, and ignores .provenance/cache/. In a workspace with multiple packages, use cargo provenance init --package <name>.

For a TypeScript project, run:

npx --yes @quality-sh/create-provenance

The TypeScript initializer detects npm, pnpm, Yarn, Bun, Deno, or Nub.

To build the CLI from this source tree:

cargo build --release -p provenance-cli --features scanner

The binaries land at target/release/provenance and target/release/cargo-provenance. Put them on your PATH.

Development builds and tests retain file and line information for backtraces. For full variable inspection in a debugger, use CARGO_PROFILE_DEV_DEBUG=2 cargo build or CARGO_PROFILE_TEST_DEBUG=2 cargo test. See the operation generation guide before a workspace build.

For parallel test execution, install cargo-nextest and run cargo nextest run --workspace --all-features. Run cargo test --workspace --all-features --doc for doctests. The repository configuration serializes PDF onboarding and limits tests that invoke Cargo. Linux CI uses the ci profile with eight test slots. Ordinary cargo test continues to work.

Quick start

# install the development dependency and set up the repository
npx --yes @quality-sh/create-provenance

# put something in the graph
npx provenance requirements create --scope default --id req_exports \
  --statement "Exports finish in under a minute"

# see where things stand
npx provenance prime

Essential commands

| Command | What it does | | --- | --- | | provenance prime | Bounded low-res graph frontier; proposals surface separately when evidence or claimed territory demands them | | provenance check | Validate the state files | | provenance materialize | Rebuild the SQLite query cache | | provenance graph <requirement> | Show the neighbourhood of a requirement | | provenance graph-reference issue\|show\|verify\|exact-export | Hand off an immutable pinned graph | | provenance traceability <rule> | Walk a Rule back to its Requirement and any producing Resolution | | provenance proposals surface --scope default --changed-path <path> | Surface undisposed proposals when current work touches their evidence or explicit territory | | provenance wiki build / provenance wiki serve | Build or serve the generated wiki with domain browsing and offline search | | provenance coverage scan --path . --validate-rules | Check bindings and report active Rules with no implementation or verification | | provenance sdk check-statement / provenance sdk apply / provenance sdk verification-runs | ASD-STE100 statement preflight, typed desired state, and callback evidence protocol | | provenance stale --since main | Report whether a diff touched, moved, or removed any graph evidence path | | provenance skills install | Install the bundled agent skills (provenance-shaping, provenance-fork-tournament, provenance-swarm-backtrace, provenance-grounded-writing) |

The repository uses the skills/<name>/SKILL.md layout, so the bundled skills can also be installed through the skills.sh ecosystem with npx skills add <owner/repo>.

Documentation

• Shaping, the refinement method and how agent sessions run it
• CLI, the full command surface
• State format and cache, how storage works
• TypeScript SDK POC, typed declarations, Node verification, and findings

Licensed under BUSL-1.1.