signum

Signum

A deterministic proof gate for agentic software development.

Signum helps teams use AI coding agents more safely by turning every change into a contract-driven, auditable workflow.

Instead of trusting that an agent “probably did the right thing”, Signum asks for evidence:

• What was the contract?
• What changed?
• Which checks passed?
• What risks were found?
• What artifacts prove the result?
• Is this safe enough to merge?

At the end, Signum produces a proofpack: a structured evidence bundle that CI and humans can inspect.

---

Why Signum?

AI agents can move fast, but fast changes need reliable boundaries.

Signum adds a release-style verification layer around agentic work:

• Contract-first execution — define intent, scope, and acceptance criteria before implementation.
• Deterministic checks — validate what can be checked without relying on model judgment.
• Policy scanning — catch risky code patterns, dependency changes, secrets, and incomplete work.
• Proofpack output — package evidence into a structured artifact.
• GitHub-ready CI gate — make merge decisions easier to review.

Signum is not a replacement for engineering judgment. It is a guardrail system that makes agentic changes easier to inspect, reproduce, and trust.

---

How it works

Signum follows a simple flow:

Contract → Execute → Audit → Pack → CI Gate

1. Contract

A change starts with a contract: the requested outcome, boundaries, risks, and acceptance criteria.

2. Execute

The implementation runs against the contract. Signum keeps the work tied to the original intent.

3. Audit

Signum runs deterministic checks and policy scans. Optional reviewer tools can add additional review signals.

4. Pack

Signum creates a proofpack: a structured evidence bundle containing the contract, diff, checks, audit summary, and decision metadata.

5. CI Gate

GitHub Actions can validate the proofpack and expose the result as a merge gate.

---

What Signum produces

The .signum/ directory is a structured registry/state/archive namespace; normal runs do not create root artifact files or root runtime dirs directly in the root .signum/ folder.

• Normal runs do not create root runtime dirs like .signum/reviews/.
• resume checks use the registry first, with root .signum/contract.json only as a legacy import signal.

A Signum run writes canonical artifacts under:

.signum/contracts/<contractId>/

Typical artifacts include:

contract.json
contract-engineer.json
contract-policy.json
combined.patch
execute_log.json
mechanic_report.json
policy_scan.json
holdout_report.json
audit_summary.json
proofpack.json

The most important output is:

proofpack.json

This is the evidence bundle used by CI and reviewers.

---

Quick start

Requirements

Signum expects a minimal local toolchain (>= v4.18.0):

bash
git
jq
python3

Initialize a project

Use the canonical init command:

/signum:init --harness

For Claude Code usage, install the Claude Code CLI according to your environment.

Optional reviewer tools may be used when available, but Signum keeps deterministic checks separate from model-based review.

Run local deterministic checks

bash scripts/run-deterministic-tests.sh

Run clean-room smoke

bash scripts/run-cleanroom-smoke.sh

For a deeper pre-publish check:

SIGNUM_CLEANROOM_FULL=1 bash scripts/run-cleanroom-smoke.sh

Validate a proofpack

python3 scripts/validate_proofpack.py \
  .signum/contracts/<contractId>/proofpack.json \
  --repo-root .

---

GitHub CI gate

Signum includes a GitHub Actions template for validating proofpacks in CI.

The CI path is intentionally deterministic:

• no hidden background work;
• no required external AI reviewer;
• no secrets needed for deterministic tests;
• pinned GitHub Actions refs;
• fixed Ubuntu runner label;
• clean-room smoke coverage.

The high-risk PR intake gate is intentionally strict. PRs touching sensitive paths such as workflows, scripts, command orchestration, or policy logic may require maintainer review or override.

---

Safety model

Signum separates three kinds of evidence.

Deterministic evidence

Checks that can run without model judgment:

• proofpack validation;
• policy scanner;
• DSL runner validation;
• artifact path guards;
• command renderer parity;
• clean-room smoke tests.

Model-assisted review

Optional reviewer outputs can be included when available, but they are treated as review signals, not as the only source of truth.

Human review

Large or high-risk changes still require human judgment. Signum makes that review easier by packaging the relevant evidence.

---

Policy scanner