Signum
Signum is a contract-first proof gate for agentic software changes: it turns a task into a reviewed contract, executes against that contract, audits the result, and packages evidence that humans and CI can inspect.
Status
Signum is an active, experimental baseline for local deterministic development and review workflows. It is not a production certification system.
The canonical runtime docs are:
commands/signum.md for the main CONTRACT → EXECUTE → AUDIT → PACK pipeline.commands/init.md for project bootstrap with /signum:init.
This README is an entry point, not the complete runtime specification. Use docs/reference.md when exact behavior matters.
What Signum does
Signum follows one mental model:
CONTRACT → EXECUTE → AUDIT → PACK
First it defines acceptance criteria and scope, then it implements against that contract, audits deterministic and model-assisted evidence, and writes a proofpack for review or CI gating.
Install
Signum expects this local toolchain:
bash
git
jq
python3
For Claude Code, install the plugin from the Emporium marketplace:
claude plugin marketplace add heurema/emporium
claude plugin install signum@emporium
claude "/signum explain"
For Codex App, Signum ships plugin metadata in this repository: .codex-plugin/plugin.json, .agents/plugins/marketplace.json, and platforms/codex/.codex-plugin/plugin.json. In Plugins -> Add marketplace, use:
Source: heurema/signum
Git ref: main
Sparse paths: leave blank
After the marketplace is added, it appears in the Plugins source dropdown as Heurema; the installable plugin inside it is Signum. For fuller setup and platform notes, see QUICKSTART.md.
First run
Run the main pipeline with a task:
/signum "your task"
Signum asks for contract approval before execution. Normal run artifacts are written under:
.signum/contracts/<contractId>/
Command surface
| Command | Purpose |
|---|
/signum "<task>" | Run the canonical Signum pipeline. |
/signum explain | Explain the current pipeline and artifact model. |
/signum archive [contractId] | Archive a completed contract; uses the active contract when no ID is provided. |
/signum close [contractId] | Close or abandon a contract without generating a proofpack; uses the active contract when no ID is provided. |
/signum:init | Bootstrap project context files. |
/signum:init --harness | Bootstrap project context and scaffold repo-level harness docs. Requires Signum >= v4.18.0. |
/signum:init --force | Overwrite existing bootstrap files. |
/signum:init --project-root <path> | Run bootstrap against a specific project root. |
Use the colon form for init commands: /signum:init is the canonical init surface.
Artifact model
.signum/contracts/<contractId>/ is the canonical active contract artifact root. It holds run evidence such as contract.json, combined.patch, audit_summary.json, and proofpack.json.
Root .signum/ is a registry/state/archive namespace with compatibility helpers; normal runs do not create root artifact files or root runtime dirs there.
For compatibility, resume checks use the registry first, with root .signum/contract.json only as a legacy import signal.
For the detailed artifact inventory, see docs/artifact-path-inventory.md and docs/reference.md.
CI integration
Run the CI wrapper with:
bash lib/signum-ci.sh
The GitHub Actions workflow template lives at:
lib/templates/signum-gate.yml
lib/signum-ci.sh maps proofpack decisions to exit codes:
| Exit code | Decision |
|---|
0 | AUTO_OK |
1 | AUTO_BLOCK |
78 | HUMAN_REVIEW |
The template uploads proofpack artifacts and comments the decision on pull requests. See lib/signum-ci.sh, lib/templates/signum-gate.yml, and docs/reference.md for the full CI behavior.
Documentation
docs/README.md — documentation index separating runtime references, maintainer docs, and historical context.QUICKSTART.md — setup and first-run walkthrough.examples/README.md — small, validator-backed examples for proofpacks, CI gating, and contract shape.docs/how-it-works.md — pipeline narrative and phase details.docs/reference.md — canonical reference for behavior, artifacts, and schemas.docs/api-reference.md — concise integration index for schemas and deterministic scripts.docs/migration-notes.md — compatibility notes for historical artifact roots, proofpack schema versions, and init command naming.docs/RELIABILITY.md — reliability notes and critical journeys.docs/SECURITY.md — trust boundaries and security review triggers.ARCHITECTURE.md — system overview and component map.
Limitations
- Policy scanning is deterministic and regex-based, not a full semantic parser.
- Optional reviewer tools depend on external CLI availability and authentication.
- High-risk changes can still require maintainer review or an explicit override.
- Clean-room smoke checks are not a real package publish/install test.
Development
Run the deterministic test suite:
bash scripts/run-deterministic-tests.sh
The suite includes scripts/check_version_bump.py, which fails runtime/plugin
surface changes unless .claude-plugin/plugin.json increases the Signum plugin
version.
Useful focused checks while editing docs:
bash tests/test-doc-parity.sh
bash lib/doc-parity-check.sh
Maintainer release checks stay lower-level and deterministic:
bash lib/release-smoke.sh
The Sync Emporium marketplace entry workflow updates heurema/emporium/.claude-plugin/marketplace.json; non-dry-run sync needs EMPORIUM_SSH_KEY. It supports workflow_dispatch for controlled manual runs.
