waiver-writer

Write an evidence waiver that records why a spec requirement is being bypassed and when it should be revisited.

When to use a waiver

Only create a waiver when:

• The required evidence is architecturally impossible (e.g., E4 for a design-only spec)
• The evidence will be deferred to a future milestone with a known date
• A conscious risk decision has been made and approved

Do not waive requirements just because they're inconvenient. Prefer lowering the required_evidence threshold in the spec instead.

Inline waiver format (spec frontmatter)

waivers:
  - kind: missing-verification     # e.g. missing-verification, missing-implementation
    target: "*"                    # dimension or subject targeted
    owner: eng-lead                # accountable person or team (not a role title)
    reason: "Human-readable justification — why this is acceptable"
    expires: "2026-09-30"          # ISO date after which the waiver must be renewed

After adding, run specgraph waivers to confirm the waiver is recognized.

Standalone waiver file

Create a file at docs/waivers/<SPEC-ID>-<dimension>.md:

---
spec_id: SPEC-001
dimension: implementation
reason: "Detailed justification"
expires: "2026-09-30"
approved_by: "Team Lead"
---

## Context

Explain the architectural or timeline constraint that makes this evidence unreachable.

## Risk acknowledgement

State what risk is accepted by waiving this requirement.

## Renewal condition

Describe what must be true before this waiver is renewed or removed.

Use a standalone file when:

• The justification is long or references external documents
• The spec is in accepted state (stronger justification required)
• Multiple dimensions need separate waivers with different owners

Checking waivers

specgraph waivers            # list all active waivers
specgraph waivers SPEC-001   # waivers for one spec

Rules

1. Set expires no more than 90 days out unless there is a documented milestone dependency.
2. owner / approved_by must name an accountable person or team, not a role title.
3. The reason must be self-contained — it should make sense without reading other context.
4. After adding a waiver, run specgraph waivers to confirm it is recognized.
5. Waivers for accepted-state specs require stronger justification than in_progress specs.
6. Config file is .specgraph/config.json (falls back to .agent-docs/config.json).