git:20260826.34a9b20 to git:20260902.afc4b94

---

name: spec-review

description: Multi-provider SPEC review gate skill

compatibility: omp

---

# SPEC Review Gate Skill

A review gate that validates SPEC document quality using multiple providers.

The CLI writes the authoritative promotion receipt to

`{SPEC_DIR}/review-receipt.json` with

`schema=spec_review_promotion_receipt.v1`. Consumers bind it to the current

invocation with `run_id` and `finished_at`, then preserve `analysis_verdict`,

`gate_status`, `critical_veto`, `status_changed`, `degraded_reasons`, and

`override_applied` without recomputing promotion.

`--allow-degraded` is the only operator path that may promote a degraded PASS,

and its audit reason remains present after promotion. An unresolved Critical

security/correctness finding sets `critical_veto=true`, keeps

`gate_status=blocked`, and leaves the prior status unchanged.

## Review Process

### Step 0: spec-writer self-verify

Look for observable traces such as `research.md`'s `## Self-Verify Summary` or `spec.md`'s `## Open Issues`.

Also prefer the draft's `## Outcome Lock`, `## Completion Debt`, `## Evolution Ideas`, `## Reviewer Brief`, `## Traceability Matrix`, and `## Reference Discipline` as scope-control evidence: review listed blockers and invariants first, treat Completion Debt as blocking, and treat Evolution Ideas or unrelated deeper-layer suggestions as advisory unless they expose critical/security/data integrity risk.

Do not create or request follow-up/sibling SPECs from Evolution Ideas. A sibling SPEC request is valid only when the draft includes a `## Sibling SPEC Decision` with an allowed reason and bounded ownership.

If the checklist was skipped or obviously not reflected in the draft, call that out as a completeness or style finding before continuing.

### Step 1: Load SPEC

Load `.autopus/specs/SPEC-{ID}/spec.md` and extract requirements.

### Step 2: Collect Code Context

If `spec.review_gate.auto_collect_context: true`:

- Scan project source files

- Collect relevant code within `context_max_lines` limit

- Include collected code in the review prompt

### Step 3: Multi-Provider Review

Run the review via the Orchestra engine with configured providers (claude, gemini, etc.):

- Each provider reviews the SPEC independently

- Auxiliary documents (`plan.md`, `research.md`, `acceptance.md`) are injected in full by default under an adaptive total context budget. Structure-preserving compression is a fallback that triggers only when the combined budget is exceeded, and it keeps tail-critical sections (Self-Verify Summary, Traceability Matrix, Reviewer Brief, Completion Debt, Evolution Ideas, Open Issues) instead of dropping the document tail.

- Provider quorum: the gate counts how many providers returned a usable review and compares it to the configured minimum (`spec.review_gate.min_providers`, default majority of configured providers).

- Results are merged according to the strategy (debate, consensus, etc.)

- Provider integrity retains requested, configured, resolved, attempted,

usable, and failed sets; configured-but-unavailable providers do not vanish

from the declared quorum denominator.

- Structured findings are clustered by stable identity, preserve minority

evidence, and apply Critical veto before promotion.

### Step 4: Verdict

Parse results and determine the final verdict:

- **PASS**: SPEC approved; promote status to "approved" only when observation is complete and the provider quorum is met

- **REVISE**: Revision required, return with list of findings

- **REJECT**: Fundamental redesign required

A PASS produced under partial observation is a degraded PASS and does not auto-promote status. The verdict is annotated with a degraded reason:

- `partial_doc_context`: a required auxiliary document was injected below 100 percent coverage because the document set exceeded the total context budget

- `provider_quorum`: fewer providers returned a usable review than the configured minimum

When any degraded reason is present, leave the prior SPEC status unchanged unless the operator passes `--allow-degraded`.

Report `run_id`, `finished_at`, `analysis_verdict`, `gate_status`,

`critical_veto`, `status_changed`, `degraded_reasons`, and `override_applied`

in `{SPEC_DIR}/review-receipt.json` and the terminal handoff. Consumers must

also verify `current_status`; they never edit SPEC status themselves. A clean

re-review of an already-approved SPEC may report `status_changed=false` while

remaining `gate_status=passed` and `current_status=approved`.

### Step 5: Save Results

Save `review.md` to the SPEC directory:

- Final verdict, with any degraded reason on the verdict line

- An `## Observation Coverage` section listing each auxiliary document with injected lines, source total lines, coverage percent, and a complete flag

- Findings from each provider

- Original responses

- When `--allow-degraded` promoted a degraded PASS, an audit line recording the override reason

The same per-document coverage is persisted in the `review-findings.json` sidecar as an additive, optional `DocCoverages` field, so older sidecars written without it still load.

## CLI Usage

```bash

auto spec review SPEC-PIPE-001

auto spec review SPEC-AUTH-001 --strategy debate --timeout 180

auto spec review SPEC-AUTH-001 --strategy debate --providers claude,codex

auto spec review SPEC-AUTH-001 --allow-degraded # promote a degraded PASS; recorded as an audit line

```

`--providers` is an explicit comma-separated provider override. Forward the

user-supplied list unchanged; omit the flag only when the user supplied no

override.

Do not wrap these commands with GNU `timeout` (for example,

`timeout 540 auto spec review ...`). macOS does not include GNU `timeout` by

default. Use the agent tool's native timeout/background control for wall-clock

limits, and use `--timeout <seconds>` for Autopus provider execution limits.

## Configuration (autopus.yaml)

```yaml

spec:

review_gate:

enabled: true

strategy: debate

providers: [claude, gemini]

judge: claude

max_revisions: 2

min_providers: 0 # 0 = default minimum quorum (majority: len/2+1 of configured providers)

auto_collect_context: true

context_max_lines: 0 # unset; adaptive limits are 500/1500/3000 by cited file count

```

## Provider Fallback

If a configured provider binary is not installed:

- Skip that provider and output a warning

- Continue review with available providers only

- Return an error if no providers are available