{"id":47395798,"url":"https://github.com/heurema/signum","last_synced_at":"2026-06-29T07:02:09.097Z","repository":{"id":340518453,"uuid":"1166408961","full_name":"heurema/signum","owner":"heurema","description":"Risk-adaptive development pipeline with adversarial consensus code review","archived":false,"fork":false,"pushed_at":"2026-05-29T14:53:41.000Z","size":3245,"stargazers_count":17,"open_issues_count":1,"forks_count":2,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-29T16:22:03.142Z","etag":null,"topics":["ai-agent","anthropic","claude","claude-code","claude-code-plugin","code-review","development-pipeline"],"latest_commit_sha":null,"homepage":"https://skill7.dev/signum","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/heurema.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":"SUPPORT.md","governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":"DCO.md","cla":null}},"created_at":"2026-02-25T07:33:50.000Z","updated_at":"2026-05-29T14:53:45.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/heurema/signum","commit_stats":null,"previous_names":["real-ai-engineering/sigil","heurema/sigil","heurema/signum"],"tags_count":33,"template":false,"template_full_name":null,"purl":"pkg:github/heurema/signum","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/heurema%2Fsignum","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/heurema%2Fsignum/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/heurema%2Fsignum/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/heurema%2Fsignum/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/heurema","download_url":"https://codeload.github.com/heurema/signum/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/heurema%2Fsignum/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34916411,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-29T02:00:05.398Z","response_time":58,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agent","anthropic","claude","claude-code","claude-code-plugin","code-review","development-pipeline"],"created_at":"2026-03-20T06:00:29.777Z","updated_at":"2026-06-29T07:02:09.092Z","avatar_url":"https://github.com/heurema.png","language":"Shell","funding_links":[],"categories":[":tada: New","CLI \u0026 Local Workflows"],"sub_categories":[],"readme":"# Signum\n\nSignum 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.\n\n## Status\n\nSignum is an active, experimental baseline for local deterministic development and review workflows. It is not a production certification system.\n\nThe canonical runtime docs are:\n\n- `commands/signum.md` for the main `CONTRACT → EXECUTE → AUDIT → PACK` pipeline.\n- `commands/init.md` for project bootstrap with `/signum:init`.\n\nThis README is an entry point, not the complete runtime specification. Use `docs/reference.md` when exact behavior matters.\n\n## What Signum does\n\nSignum follows one mental model:\n\n```text\nCONTRACT → EXECUTE → AUDIT → PACK\n```\n\nFirst 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.\n\n## Install\n\nSignum expects this local toolchain:\n\n```text\nbash\ngit\njq\npython3\n```\n\nFor Claude Code, install the plugin from the Emporium marketplace:\n\n```bash\nclaude plugin marketplace add heurema/emporium\nclaude plugin install signum@emporium\nclaude \"/signum explain\"\n```\n\nFor 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 -\u003e Add marketplace**, use:\n\n```text\nSource: heurema/signum\nGit ref: main\nSparse paths: leave blank\n```\n\nAfter 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`.\n\n## First run\n\nRun the main pipeline with a task:\n\n```text\n/signum \"your task\"\n```\n\nSignum asks for contract approval before execution. Normal run artifacts are written under:\n\n```text\n.signum/contracts/\u003ccontractId\u003e/\n```\n\n## Command surface\n\n| Command | Purpose |\n| --- | --- |\n| `/signum \"\u003ctask\u003e\"` | Run the canonical Signum pipeline. |\n| `/signum explain` | Explain the current pipeline and artifact model. |\n| `/signum archive [contractId]` | Archive a completed contract; uses the active contract when no ID is provided. |\n| `/signum close [contractId]` | Close or abandon a contract without generating a proofpack; uses the active contract when no ID is provided. |\n| `/signum:init` | Bootstrap project context files. |\n| `/signum:init --harness` | Bootstrap project context and scaffold repo-level harness docs. Requires Signum `\u003e= v4.18.0`. |\n| `/signum:init --force` | Overwrite existing bootstrap files. |\n| `/signum:init --project-root \u003cpath\u003e` | Run bootstrap against a specific project root. |\n\nUse the colon form for init commands: `/signum:init` is the canonical init surface.\n\n## Artifact model\n\n`.signum/contracts/\u003ccontractId\u003e/` is the canonical active contract artifact root. It holds run evidence such as `contract.json`, `combined.patch`, `audit_summary.json`, and `proofpack.json`.\n\nRoot `.signum/` is a registry/state/archive namespace with compatibility helpers; normal runs do not create root artifact files or root runtime dirs there.\n\nFor compatibility, resume checks use the registry first, with root `.signum/contract.json` only as a legacy import signal.\n\nFor the detailed artifact inventory, see `docs/artifact-path-inventory.md` and `docs/reference.md`.\n\n## CI integration\n\nRun the CI wrapper with:\n\n```bash\nbash lib/signum-ci.sh\n```\n\nThe GitHub Actions workflow template lives at:\n\n```text\nlib/templates/signum-gate.yml\n```\n\n`lib/signum-ci.sh` maps proofpack decisions to exit codes:\n\n| Exit code | Decision |\n| --- | --- |\n| `0` | `AUTO_OK` |\n| `1` | `AUTO_BLOCK` |\n| `78` | `HUMAN_REVIEW` |\n\nThe 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.\n\n## Documentation\n\n- `docs/README.md` — documentation index separating runtime references, maintainer docs, and historical context.\n- `QUICKSTART.md` — setup and first-run walkthrough.\n- `examples/README.md` — small, validator-backed examples for proofpacks, CI gating, and contract shape.\n- `docs/how-it-works.md` — pipeline narrative and phase details.\n- `docs/reference.md` — canonical reference for behavior, artifacts, and schemas.\n- `docs/api-reference.md` — concise integration index for schemas and deterministic scripts.\n- `docs/migration-notes.md` — compatibility notes for historical artifact roots, proofpack schema versions, and init command naming.\n- `docs/RELIABILITY.md` — reliability notes and critical journeys.\n- `docs/SECURITY.md` — trust boundaries and security review triggers.\n- `ARCHITECTURE.md` — system overview and component map.\n\n## Limitations\n\n- Policy scanning is deterministic and regex-based, not a full semantic parser.\n- Optional reviewer tools depend on external CLI availability and authentication.\n- High-risk changes can still require maintainer review or an explicit override.\n- Clean-room smoke checks are not a real package publish/install test.\n\n## Development\n\nRun the deterministic test suite:\n\n```bash\nbash scripts/run-deterministic-tests.sh\n```\n\nThe suite includes `scripts/check_version_bump.py`, which fails runtime/plugin\nsurface changes unless `.claude-plugin/plugin.json` increases the Signum plugin\nversion.\n\nUseful focused checks while editing docs:\n\n```bash\nbash tests/test-doc-parity.sh\nbash lib/doc-parity-check.sh\n```\n\nMaintainer release checks stay lower-level and deterministic:\n\n```bash\nbash lib/release-smoke.sh\n```\n\nThe `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.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fheurema%2Fsignum","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fheurema%2Fsignum","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fheurema%2Fsignum/lists"}