spec-review

SPEC Review Gate Skill

A review gate that validates SPEC document quality using multiple providers. Before Step 1, treat .omp/rules/autopus-spec-quality.md as the pre-review self-check that spec-writer should already have applied to spec.md, plan.md, acceptance.md, and research.md.

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

Confirm that the draft went through a first-pass self-check using .omp/rules/autopus-spec-quality.md. 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

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)

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