# Signum Reference

## Canonical Sources

Signum has multiple documentation surfaces, but they do not have equal authority.

- **Canonical pipeline behavior:** root `commands/signum.md`
- **Platform-specific overlays:** `platforms/*/commands/signum.md`
- **Derived docs:** `README.md`, `docs/how-it-works.md`, `docs/reference.md`, roadmap docs

If a derived doc disagrees with root `commands/signum.md`, treat the command file as the source of truth. Platform overlays may add surface-specific behavior, but they should be read as explicit deviations from the root pipeline rather than independent definitions of core Signum behavior.

### Known overlay deviations

- `platforms/claude-code/commands/signum.md` currently adds **Phase 5: RECONCILE** after PACK.
- This is an **overlay-only deviation**, not canonical core pipeline behavior.
- Treat it as valid only while it remains listed in `docs/overlay-deviations.json`.

## Usage

```
/signum <task description>
```

Signum parses the task description and runs the full 4-phase pipeline automatically.

## Examples

### Simple feature (low risk)

```
/signum add a health check endpoint that returns 200 OK
```

Pipeline: contractor → baseline → engineer (1 attempt) → scope gate → mechanic + Claude review → proofpack.
Estimated cost: ~$0.10-0.20.

### Authentication (medium risk)

```
/signum add user authentication with JWT tokens
```

Pipeline: contractor → baseline → engineer (up to 3 repair attempts) → scope gate → mechanic + holdouts + Claude + Codex (security) + Gemini (performance) → synthesizer → proofpack.
Estimated cost: ~$0.30-0.60.

### Database migration (high risk)

```
/signum migrate user table from MongoDB to PostgreSQL
```

Pipeline: same as medium but contractor flags high risk with risk signals and holdout scenarios. All 3 model reviews weighted equally in synthesis.
Estimated cost: ~$0.50-1.00.

### Resume interrupted pipeline

```
# Start a pipeline
/signum refactor the payment module

# ...interrupt (Ctrl+C or close session)...

# Reopen and run the same command
/signum refactor the payment module
# Signum checks contracts/index.json.activeContractId and asks: resume from Phase 2, or restart?
```

## Pipeline Phases

```
CONTRACT → EXECUTE → AUDIT → PACK
```

### Phase 1: CONTRACT

Contractor agent (haiku) scans the codebase and produces `contract.json` under the active contract artifact root (`.signum/contracts/<contractId>/`). Root `.signum/contract.json` is only a legacy import signal.

Hard stop if `openQuestions` is non-empty — the user must answer before proceeding.

### Phase 2: EXECUTE

1. **Baseline capture** — orchestrator runs lint/typecheck/tests BEFORE any changes and saves `baseline.json` under the active contract artifact root.
2. **Codebase Awareness context** — when enabled with `SIGNUM_CODEBASE_AWARENESS=hint|warn|gate`, orchestrator writes the derived project cache under `.signum/cache/` and run-scoped `implementation_context.json` / `reuse_candidates.json` under the active contract artifact root. The rebuildable project cache includes `codebase-index-v1.json`, `style-profile-v1.json`, `file-digests-v1.json`, and `file-extracts-v1.json`; the digest and extraction caches support bounded/incremental lexical scanning only and do not introduce AST, semantic, or external-tool scanning.
3. **Engineer agent** (sonnet) implements the contract. When Codebase Awareness artifacts exist, the Engineer records `reuse_decision.json` before code changes; `warn` and `gate` modes require it by protocol, including top/strong candidate coverage and `candidateId` for action-bearing decisions.
4. **Reuse decision validation** — after the Engineer returns, `hint` remains advisory; `warn` mode emits warnings for missing, invalid, or incomplete-coverage `reuse_decision.json` and continues; `gate` mode blocks EXECUTE on missing, invalid, or incomplete-coverage decisions. PACK summarizes this evidence later in `reuse_summary.json`.
5. **Scope gate** — deterministic check that all modified files are within `inScope` or `allowNewFilesUnder`. Pipeline stops on scope violation.

Outputs under the active contract artifact root: `baseline.json`, `implementation_context.json`, `reuse_candidates.json`, `reuse_decision.json`, `combined.patch`, `execute_log.json`.

### Phase 3: AUDIT

Six independent verification layers:

1. **Mechanic** (bash, zero LLM) — runs linter, typechecker, tests. Compares with baseline to detect regressions vs pre-existing failures.
2. **Codebase Awareness duplicate scan** (bash/Python, zero LLM) — when enabled, writes `duplicate_scan.json` as audit evidence. In `warn`, unresolved major/critical duplicate findings cap the final outcome at `HUMAN_REVIEW`; in `gate`, critical and narrow high-confidence major duplicate findings can force `AUTO_BLOCK`.
3. **Holdout validation** — runs hidden acceptance criteria the Engineer never saw (edge cases, negative tests from contract).
4. **Claude reviewer** (opus agent) — semantic review of contract + diff + mechanic results.
5. **Codex reviewer** (CLI, security-focused) — analyzes diff for security defects using `review-template-security.md`.
6. **Gemini reviewer** (CLI, performance-focused) — analyzes diff for performance defects using `review-template-performance.md`.

Synthesizer agent applies deterministic rules:
- **AUTO_OK**: no regressions + all reviews APPROVE + 2+ reviews parsed + holdouts pass
- **AUTO_BLOCK**: any regression (NEW failure vs baseline) OR any REJECT OR any CRITICAL finding
- **HUMAN_REVIEW**: everything else (mixed signals, only 1 review, CONDITIONAL verdicts, holdout failures)

Codebase Awareness verdict mapping is applied after synthesis and preserves stricter existing verdicts. `hint` remains informational. `warn` never produces `AUTO_BLOCK` from duplicate findings.

Pre-existing failures (checks that failed in baseline AND still fail) no longer auto-block.

### Phase 4: PACK

Assembles `proofpack.json` under the active contract artifact root — a self-contained evidence bundle with embedded artifact contents, SHA-256 checksums, and confidence score. When Codebase Awareness is enabled, PACK also writes `reuse_summary.json` and includes/references compact Codebase Awareness evidence in the proofpack without embedding project-level cache files.

`scripts/codebase_awareness/summarize_dogfood_run.py` is an optional reporting-only helper for Codebase Awareness dogfood. It summarizes existing active-contract artifacts and project-level cache stats, is not required for Signum runs, and does not change EXECUTE, AUDIT, PACK, scanner, matcher, or audit behavior.

## Artifacts

Canonical run artifacts live under the active contract artifact root `.signum/contracts/<contractId>/`. Root `.signum/` stays auto-added to `.gitignore` and is a registry/state/archive namespace, not a runtime workspace. Normal runs do not create root artifact files or root runtime dirs; root artifact paths are legacy migration inputs only. The contract, pre-execute metadata, execute outputs, selected audit/pack file artifacts (`contract.json`, `spec_quality.json`, `spec_validation.json`, `clover_report.json`, `intent_check.json`, `approval.json`, `contract-hash.txt`, `contract-engineer.json`, `contract-policy.json`, `execution_context.json`, `baseline.json`, `implementation_context.json`, `reuse_candidates.json`, `reuse_decision.json`, `duplicate_scan.json`, `reuse_summary.json`, `combined.patch`, `execute_log.json`, `iteration_delta.patch`, `mechanic_report.json`, `holdout_report.json`, `policy_violations.json`, `policy_scan.json`, `audit_iteration_log.json`, `repair_brief.json`, `flaky_tests.json`, `audit_summary.json`, `proofpack.json`, `anti_entropy_report.json`), and active run directories (`reviews/`, `iterations/`, `receipts/`, `runs/`, `snapshots/`) are canonical under that contract directory. Project-level Codebase Awareness cache files live under `.signum/cache/`.

`.signum/cache/file-digests-v1.json` is a rebuildable project-level Codebase Awareness cache. It is not active contract root evidence, not run-scoped evidence, and not a proofpack payload. The scanner may use it with `--previous-digests` as a bounded incremental foundation, but the current cache remains lexical and does not add AST, semantic, or external-tool scanning.

`.signum/cache/file-extracts-v1.json` is a rebuildable project-level Codebase Awareness cache. It stores per-file scanner extraction payloads for unchanged indexed files and includes a deterministic extractor ABI marker for the core scanner and language adapters. It may be reused with `--previous-extracts` only when the repo-relative path, SHA-256, size, schema version, scan mode, extractor version, and extractor ABI are compatible. Signum ignores incompatible previous extraction caches and performs a full extraction. Cache invalidation is local and deterministic, based on schema/scan/extractor ABI compatibility. It is not active contract root evidence, not run-scoped evidence, and not a proofpack payload. The cache is derived from the same shallow stdlib scanner. Neither cache adds AST, semantic, or external-tool scanning; no network behavior is introduced.

The scanner defaults are bounded: `--max-files 10000`, `--max-bytes 50000000`, and `--max-file-size 1048576`. Files over the per-file cap are skipped, and repository-level caps mark the scan as truncated while still producing degraded cache/index artifacts.

Codebase Awareness has shallow Go, Rust, C#, and TypeScript/JavaScript lexical/symbol support, plus Python and Bash/Shell lexical/symbol support. For Go, it detects `go.mod`, `go.work`, `.go` files, Go package names/imports, exported symbols, `internal/`, `cmd/`, `pkg/`, `testdata/`, and `*_test.go` conventions. Go import resolution is local and module-path based when possible. For Rust, it detects `Cargo.toml` manifests and workspaces, Cargo package/dependency hints, Rust modules/imports, `pub` symbols, crate and module boundary hints, integration tests under `tests/`, and inline `#[cfg(test)]` tests. For C#, it detects `.sln`, `.csproj`, `Directory.Build.props`, `Directory.Build.targets`, `.cs` files, project references, package references, namespaces, `using` imports, public/internal symbols, project and assembly boundary hints, and common .NET test frameworks such as xUnit, NUnit, MSTest, and `Microsoft.NET.Test.Sdk`. For TypeScript/JavaScript, it detects `package.json` workspaces, npm/pnpm/yarn lockfiles, `tsconfig`/`jsconfig` hints, imports/exports, exported and local symbols, tests, package boundaries, CLI `bin` entrypoints, and package/workspace reuse signals. For Python, it detects `pyproject.toml`, `setup.py`, `setup.cfg`, `requirements.txt`, `requirements/*.txt`, `Pipfile`, `poetry.lock`, `uv.lock`, `.py` files, package `__init__.py` boundaries, local imports, public/private functions/classes/methods/constants, pytest/unittest/Hypothesis conventions, CLI entrypoints, and shallow framework/config hints. For Bash/Shell, it detects `.sh`, `.bash`, `.zsh`, `.bats`, and common bash/sh shebang files; shell functions; `source` and dot-sourced helpers; obvious local `bash`/`sh`/`zsh` script calls; JSON-emitting checker patterns; `jq` and Python here-doc JSON validation mentions; GitHub Actions annotation emitters; shell tests; and shell helper, test, command-fragment, and executable script boundaries. It does not run `go list`, Cargo, `rustc`, `cargo metadata`, `dotnet`, MSBuild, NuGet, `node`, `npm`, `pnpm`, `yarn`, `tsc`, Jest, Vitest, Python project code, pytest, pip, Poetry, uv, PDM, ShellCheck, Bats, `jq`, or target repo `bash`/`sh`/`zsh` scripts; it does not source shell scripts, it does not use Roslyn, TypeScript compiler API, AST parsing, type checking, semantic analysis, or semantic resolution, does not perform semantic shell analysis, and it avoids external parser dependencies.

| File | Phase | Contents |
|------|-------|----------|
| `contract.json` | Contract | Goal, scope, acceptance criteria, holdout scenarios, risk level |
| `baseline.json` | Execute | Pre-change lint/typecheck/test exit codes |
| `implementation_context.json` | Execute | Codebase Awareness hint context for the active contract |
| `reuse_candidates.json` | Execute | Non-blocking reuse candidates for the active contract |
| `reuse_decision.json` | Execute | Engineer reuse/adapt/reject decision evidence; required in `warn` and `gate` modes |
| `duplicate_scan.json` | Audit | Deterministic Codebase Awareness post-diff reuse/duplicate scan evidence; affects AUDIT outcome in `warn`/`gate` |
| `reuse_summary.json` | Pack | Compact Codebase Awareness PACK evidence summarizing candidates, reuse decision, duplicate scan, and verdict impact |
| `combined.patch` | Execute | Full git diff of all changes |
| `execute_log.json` | Execute | Attempt history, check results, status |
| `mechanic_report.json` | Audit | Lint, typecheck, test results with baseline comparison and regression flags |
| `holdout_report.json` | Audit | Holdout scenario pass/fail counts |
| `reviews/claude.json` | Audit | Claude opus semantic review |
| `reviews/codex.json` | Audit | Codex CLI security review (or unavailable marker) |
| `reviews/gemini.json` | Audit | Gemini CLI performance review (or unavailable marker) |
| `audit_summary.json` | Audit | Synthesized decision with consensus reasoning and confidence scores |
| `proofpack.json` | Pack | Self-contained evidence bundle with embedded artifacts, checksums, and confidence |
| `anti_entropy_report.json` | Pack | Advisory anti-entropy follow-up findings; report-only, does not change pipeline decision |

Canonical contract directories typically contain:
- `contract.json`
- `proofpack.json`
- `anti_entropy_report.json`
- `audit_summary.json`
- `approval.json`
- `execution_context.json`
- `reviews/`
- `iterations/`
- `receipts/`
- `runs/<runId>/`
- `snapshots/`

### contract.json fields

| Field | Type | Description |
|-------|------|-------------|
| `schemaVersion` | `"3.0"`–`"3.8"` | Schema version |
| `glossaryVersion` | string | Version from `project.glossary.json` at contract creation time (optional, omitted when file absent) |
| `goal` | string | What to build (min 10 chars) |
| `inScope` | string[] | Items in scope (min 1) |
| `allowNewFilesUnder` | string[] | Directories where new files may be created (optional) |
| `outOfScope` | string[] | Explicitly excluded items |
| `acceptanceCriteria` | object[] | AC-N items with verify commands |
| `holdoutScenarios` | object[] | Hidden ACs not shown to Engineer (optional) |
| `riskLevel` | `low\|medium\|high` | Deterministic risk assessment |
| `riskSignals` | string[] | Why risk level was assigned |
| `openQuestions` | string[] | Must be empty to proceed |
| `contextInheritance` | object | Project context references (optional) |
| `contextInheritance.projectRef` | string\|null | Path to project.intent.md, "not_found", null (waiver), or absent (legacy) |
| `contextInheritance.projectIntentSha256` | string | SHA-256 of project.intent.md at contract creation |
| `contextInheritance.contextSnapshotHash` | string | SHA-256 hex digest over concatenated byte contents of all `staleIfChanged` files in array order, computed at contract creation time |
| `contextInheritance.staleIfChanged` | string[] | Upstream artifact paths tracked for staleness; at minimum includes `project.intent.md` when loaded |
| `contextInheritance.stalenessStatus` | `"fresh"\|"warning"\|"stale"` | Current staleness state: fresh=hash matches, warning=soft mismatch, stale=hash differs and policy=block |
| `contextInheritance.stalenessPolicy` | `"block"\|"warn"` | Action when upstream hash differs: block=halt pipeline (BLOCK), warn=continue with warning (default: `"warn"`) |
| `dependsOnContractIds` | string[] | ContractIds that must complete before this contract executes (user-declared, optional) |
| `supersedesContractIds` | string[] | ContractIds this contract replaces (user-declared, optional) |
| `supersededByContractId` | string | ContractId of the contract that replaces this one (optional) |
| `interfacesTouched` | string[] | Named interfaces, APIs, or module boundaries this contract modifies (optional) |
| `ambiguityCandidates` | object[] | Typed findings from ambiguity review pass: `{text, location, severity}` (optional, v3.7+) |
| `contradictionsFound` | object[] | Typed findings from contradiction review: `{claim_a, claim_b, type}` (optional, v3.7+) |
| `clarificationDecisions` | object[] | Decisions made during critique: `{question, decision, rationale}` (optional, v3.7+) |
| `assumptionProvenance` | object[] | Source tracking for assumptions: `{id, text, source, confidence}` (optional, v3.7+) |
| `readinessForPlanning` | object | Go/no-go gate: `{verdict: "go"\|"no-go", summary: string}` (optional, v3.7+) |

### project.glossary.json schema

Optional file at `PROJECT_ROOT/project.glossary.json`. When present, contractor reads it and sets `glossaryVersion` in the contract.

```json
{
  "version": "1.0.0",
  "canonicalTerms": ["term1", "term2", "..."],
  "aliases": {
    "forbidden-synonym": "canonical-term",
    "another-synonym": "another-canonical"
  }
}
```

| Field | Type | Description |
|-------|------|-------------|
| `version` | string | Glossary version string (mirrors `glossaryVersion` in contract) |
| `canonicalTerms` | string[] | Approved terminology for this project |
| `aliases` | object | Map of forbidden synonyms to their canonical replacements |

### Quality check scripts (lib/)

All Phase 1 quality checks are standalone shell scripts in `lib/`. Each follows the same interface:

```
lib/<check>.sh <contract.json> [--flag value ...]
  stdout: {"check":"<name>","status":"ok|warn|block|skip|error","summary":"...","findings":[...]}
  exit 0: check completed (any status)
  exit 1+: infra error (bad args, missing jq, corrupt input)
```

| Script | Purpose | Extra args |
|--------|---------|-----------|
| `lib/glossary-check.sh` | Forbidden synonym scan | `--glossary <path>` |
| `lib/terminology-check.sh` | Cross-contract synonym proliferation | `--index <path>` `--glossary <path>` |
| `lib/overlap-check.sh` | inScope overlap between active contracts | `--index <path>` |
| `lib/assumption-check.sh` | Assumption contradiction detection | `--index <path>` |
| `lib/adr-check.sh` | ADR relevance for inScope paths | `--project-root <dir>` |
| `lib/staleness-check.sh` | Upstream artifact staleness (pure, no mutation) | `--project-root <dir>` |
| `lib/prose-check.sh` | Prose quality gate (banned phrases, quantifiers, passive voice) | — |

The orchestrator (`commands/signum.md`) calls each script, reads JSON output, merges findings into `spec_quality.json`, and applies mutations/blocking decisions. Scripts never modify `contract.json` or `spec_quality.json` directly.

#### upstream_staleness_check

Runs during Phase 1 spec quality gate (after the `adr_relevance_check`). Skipped when `contextInheritance.staleIfChanged` is absent or empty.

When `staleIfChanged` is a non-empty array, the check always executes:

1. Concatenates the byte contents of all files listed in `staleIfChanged` (in array order)
2. Computes SHA-256 of the concatenated bytes
3. Compares the result to `contextInheritance.contextSnapshotHash`

Outcome depends on `contextInheritance.stalenessPolicy` (default `"warn"`):

| Hash result | Policy | Outcome |
|-------------|--------|---------|
| Matches | any | `fresh` — pipeline continues |
| Differs | `"warn"` | `warning` — WARN emitted, pipeline continues |
| Differs | `"block"` | `stale` — BLOCK emitted, pipeline stops; re-run Contractor to refresh |

`contextInheritance.stalenessStatus` is updated in-place in `contract.json` after the check.

#### glossary_check

Runs during Phase 1 spec quality gate (Step 1.3.5). Scans the contract's `goal`, `inScope` items, and AC `description` fields for any term appearing in the `aliases` map (case-insensitive whole-word match). Emits a `WARN` line for each match with the forbidden term and its canonical replacement. Results are written to `glossary_warnings` in `spec_quality.json`. This check is **non-blocking** — it never fails the pipeline or reduces the numeric spec quality score.

#### terminology_consistency_check

Runs during Phase 1 spec quality gate (Step 1.3.5) after `glossary_check`. Reads `.signum/contracts/index.json`, extracts goal text from active contracts, and scans for synonym proliferation (same concept appearing under two different terms across contracts). Emits `WARN` lines on synonym proliferation. When `.signum/contracts/index.json` is absent or contains no contracts with active status, the check outputs a skip message and does not block or fail. This check is **non-blocking**.

#### cross_contract_overlap_check

Runs during Phase 1 spec quality gate. Reads `.signum/contracts/index.json`, compares the new contract's `inScope` against active contracts' `inScope` arrays. Emits `WARN` when files overlap with another active contract, listing the overlapping files and the conflicting contract ID. Skips gracefully when index is absent or has no active contracts. **Non-blocking.**

#### assumption_contradiction_check

Runs during Phase 1 spec quality gate after `cross_contract_overlap_check`. Reads assumptions from the new contract and compares against assumptions of active contracts in `index.json`. Emits `WARN` when assumption text contains contradictory terms (e.g., one contract assumes "X is true" while another assumes "X is false"). **Non-blocking.**

#### adr_relevance_check

Runs during Phase 1 spec quality gate. Scans for `docs/adr/` or `docs/decisions/` directories. If ADR files exist and the contract's `inScope` touches paths that match ADR file globs, emits `WARN` suggesting the contract reference relevant ADRs. Skips when no ADR directories exist. **Non-blocking.**

### Iterative AUDIT (v4.6+)

When AUDIT finds MAJOR or CRITICAL issues, it enters an iterative repair loop:

1. Engineer fixes findings (fresh agent, clean context)
2. Full review cycle re-runs from scratch
3. Repeats until convergence or max iterations

| Environment Variable | Default | Description |
|---------------------|---------|-------------|
| `SIGNUM_AUDIT_MAX_ITERATIONS` | `20` | Maximum audit fix iterations before terminal decision |
| `SIGNUM_CI_RELAXED` | `false` | If `"true"`, HUMAN_REVIEW maps to exit 0 instead of 78 |

Iteration artifacts are stored under the active contract artifact root, for example `.signum/contracts/<contractId>/iterations/01/`, `.signum/contracts/<contractId>/iterations/02/`, etc. Each contains the full set of audit artifacts for that pass.

The proofpack includes an `iterativeAudit` section when >1 iteration was used, with per-iteration summaries, resolved/remaining findings, and the best iteration number.

### proofpack.json fields

Proofpack shape is defined by two current sources of truth:

- `lib/schemas/proofpack.schema.json` defines the documented JSON Schema surface.
- `scripts/validate_proofpack.py` is the deterministic validator for the proofpack shape Signum currently emits.

The runtime PACK phase writes the proofpack to the active contract artifact root as `.signum/contracts/<contractId>/proofpack.json`.

| Field | Required by current validator | Type / allowed values | Description |
|-------|-------------------------------|-----------------------|-------------|
| `schemaVersion` | Yes | string; schema enum `"4.0"` through `"4.8"`; current runtime emits `"4.8"` | Proofpack schema version. The validator checks it against the runtime source of truth. |
| `signumVersion` | Yes | string | Signum version that generated this proofpack. |
| `createdAt` | Yes | string | Proofpack creation timestamp. |
| `runId` | Yes | string starting with `signum-` | Runtime run identifier. |
| `contractId` | Yes | string starting with `sig-` | Links the proofpack to its source contract and canonical artifact root. |
| `decision` | Yes | `AUTO_OK\|AUTO_BLOCK\|HUMAN_REVIEW` | Final Signum decision. `checks.auditSummary.content.decision`, when embedded, must match this value. |
| `releaseVerdict` | Yes | string | Release verdict copied from `audit_summary.json`; current PACK defaults to `HOLD` when absent. |
| `riskLevel` | Yes | string | Contract risk level copied from `contract.json`; current PACK defaults to `low` when absent. |
| `summary` | Yes | string | Human-readable run summary. |
| `confidence` | Yes | object with numeric `overall` from 0 to 100 | Weighted confidence score. |
| `timing` | Yes | object | Runtime timing metadata. If present, `startedAt` and `completedAt` must be strings and `durationMs` must be numeric. Current PACK emits all three. |
| `reviewCoverage` | Yes | object | Review coverage metadata. If `availableReviews` is present, it must be an integer. Current PACK emits `availableReviews`. |
| `contractSource` | Yes | `interactive\|file\|template` | How the contract was provided. |
| `auditChain` | Yes | object | Audit anchors such as `contractSha256`, `approvedAt`, and `baseCommit`. |
| `contract` | Yes | envelope with `fullSha256` | Redacted contract evidence. The validator requires `fullSha256` to be lowercase SHA-256 hex. |
| `diff` | Yes | envelope | Patch evidence. |
| `baseline` | Yes | envelope | Pre-change check evidence. |
| `executeLog` | Yes | envelope | Execution attempt evidence. |
| `approval` | Yes | envelope | Approval-gate evidence. |
| `checks.mechanic` | Yes | envelope | Mechanic check evidence. |
| `checks.holdout` | Yes | envelope | Holdout check evidence. |
| `checks.policy_scan` | Yes | envelope | Deterministic policy-scan evidence from `policy_scan.json`. |
| `checks.reviews` | Yes | object of provider-name to envelope | Per-provider review evidence. Provider names must be non-empty strings. |
| `checks.auditSummary` | Yes | envelope | Synthesized audit summary evidence. |
| `ciContext` | Optional | object; `provider` is `github-actions\|gitlab-ci\|circleci\|local` when present | CI metadata. `runUrl` is a URI; `prNumber` is an integer; `triggerEvent` is a string. |
| `baselineComparison` | Optional | object | Previous-run comparison metadata. Numeric confidence fields are 0-100 where constrained by schema; finding counts are non-negative integers. |
| `iterativeAudit` | Optional | object | Iteration metadata, present only when AUDIT used more than one iteration. |
| `removalEvidence` | Optional | object | Removal and cleanup-obligation evidence. `removals[].id` must match `RM<number>`, paths must be safe relative paths, `removed` must be boolean, and optional `type` is `file` or `directory`. `obligations[].id` must match `CO<number>` and `fulfilled` must be boolean. |

Each artifact envelope uses this format: `{ content, sha256, sizeBytes, status, omitReason? }`.
- `status: present` — content embedded; `sha256` must be lowercase SHA-256 hex.
- `status: omitted` — content is omitted, with checksum metadata retained when available.
- `status: error` — generation failed, see `omitReason`.

Any artifact references in proofpacks must be safe relative paths. When the validator can resolve the contract root, referenced artifacts must stay inside `.signum/contracts/<contractId>/` and exist there.

### Confidence scoring

The synthesizer computes a weighted confidence score (0-100):

| Component | Weight | Source |
|-----------|--------|--------|
| `execution_health` | 40% | ACs passed ratio minus repair attempt penalty |
| `baseline_stability` | 30% | Proportion of checks with no regressions |
| `review_alignment` | 30% | Reviewer agreement level (100=unanimous approve, 0=no approvals) |

### Review JSON format

Each reviewer produces:

```json
{
  "verdict": "APPROVE|REJECT|CONDITIONAL",
  "findings": [
    {
      "severity": "CRITICAL|MAJOR|MINOR",
      "category": "bug|security|performance|spec-gap|missing-test",
      "file": "src/auth.ts",
      "line": 42,
      "description": "...",
      "suggestion": "..."
    }
  ],
  "summary": "..."
}
```

## Requirements

| Dependency | Required | Purpose |
|-----------|----------|---------|
| Claude Code | Yes | Runtime environment |
| git | Yes | Diff generation, scope gate |
| jq | Yes | JSON validation and assembly |
| python3 | Yes | Review prompt template substitution |
| sha256sum or shasum | Yes | Checksum computation (auto-detected) |
| Codex CLI | No | Security-focused review in AUDIT phase |
| Gemini CLI | No | Performance-focused review in AUDIT phase |

## Troubleshooting

### `jq: command not found`

Install jq:
- macOS: `brew install jq`
- Ubuntu/Debian: `apt install jq`
- Other: [jq downloads](https://jqlang.github.io/jq/download/)

### External provider auth errors

```
codex: auth expired → run: codex auth
gemini: auth expired → run: gemini login
```

Signum continues without the provider if auth fails.

### Provider timeout

External providers are killed after 180 seconds. The review continues with remaining providers. Check `reviews/` under the canonical artifact root for provider status.

### `.signum/` exists from previous run

Normal behavior. Signum detects existing `contract.json` and offers:
- **Resume**: continue from Phase 2
- **Restart**: clear artifacts, start fresh

### Optional: jj-supersede integration (v4.15.0+)

In jj-managed repositories, the contractor can detect ghost solutions — functions that are semantically superseded but still present in the codebase. This requires [jj-supersede](https://github.com/heurema/jj-supersede):

```bash
uv tool install jj-supersede
```

When both `jj` and `jj-supersede` are available, the contractor automatically:
1. Runs `jj-supersede report --json` during CONTRACT phase (step 1.8)
2. Generates `removals` entries with `type: "function"` for superseded functions
3. Creates non-blocking `cleanupObligations` with `action: "remove_code"`

If `jj-supersede` is not installed or the project is not a jj repo, this step is silently skipped. No configuration needed.

### Plugin not loading

1. Verify installation: `claude plugin list | grep signum`
2. Reinstall: `claude plugin install signum@emporium`
3. Open a new Claude Code session (plugins load at session start)
