docs: document TaxDiagnosticResult tri-state model

[mintlify]

Summary

Documents the new opt-in TaxDiagnosticResult 3-layer model and to_diagnostic() helpers added to TDS, ITC, and GST guards in QWED-Tax.

Changes

• Added a "Structured diagnostics" section to tax/guards.mdx covering:
  • The three layers (agent message, developer fields, proof ref) and the VERIFIED / UNVERIFIABLE / BLOCKED status states.
  • The authority contract (proof_ref is the only admissibility signal).
  • How to call to_diagnostic() on TDS, ITC, and GST guards.
  • compute_proof_ref / trace_proof_ref and how proof references detect verdict/evidence drift.
  • Factory methods (verified, unverifiable, blocked), TaxAdvisoryCheck semantics, and serialization.
  • Current migration status (3 of 12 guards).

Context

Triggered by QWED-AI/qwed-tax#45, which introduces the model as an opt-in API alongside the existing legacy dict returns.

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
qwed-ai	🟢 Ready	View Preview	Jun 21, 2026, 6:48 PM

[greptile-apps]

Greptile Summary

This PR adds a "Structured diagnostics" section to tax/guards.mdx documenting the new opt-in TaxDiagnosticResult tri-state model introduced in qwed-tax#45, covering the three-layer shape, VERIFIED/UNVERIFIABLE/BLOCKED status states, to_diagnostic() usage, proof reference helpers, factory methods, advisory checks, serialization, and current migration scope (3 of 12 guards).

• Adds ~112 lines of new reference content and code examples for TDSGuard, InputCreditGuard, and GSTGuard; all examples include imports, realistic values, and the VERIFIED/non-VERIFIED branching pattern.
• The authority contract ("proof_ref is not None is the only admissibility signal") and the __post_init__ invariant are clearly called out in a Warning block, which correctly positions the proof reference as the single gating signal.

Confidence Score: 5/5

Documentation-only change with no runtime code; all code examples are illustrative and correctly reflect the documented API contracts.

The change is purely additive MDX documentation. The authority contract, dataclass invariants, and factory method semantics are accurately described. The three issues noted are prose/example quality concerns that do not affect the correctness of the documented API.

tax/guards.mdx — the TaxAdvisoryCheck subsection and the to_diagnostic() else-branch example are the spots most likely to confuse first-time readers.

Important Files Changed

Filename	Overview
tax/guards.mdx	Adds 112 lines documenting TaxDiagnosticResult tri-state model; prose uses dot notation for dict key access in one place, TaxAdvisoryCheck section lacks a code example, and the else-branch example conflates UNVERIFIABLE and BLOCKED without comment.

Sequence Diagram

%%{init: {'theme': 'neutral'}}%%
sequenceDiagram
    participant Caller
    participant Guard as TDSGuard / InputCreditGuard / GSTGuard
    participant Diag as TaxDiagnosticResult
    participant AuditLog

    Caller->>Guard: calculate_deduction(service, amount)
    Guard-->>Caller: "raw dict {verified, audit_trace, ...}"

    Caller->>Guard: to_diagnostic(raw)
    Guard->>Diag: build(agent_message, developer_fields, proof_ref)
    Guard-->>Caller: diag : TaxDiagnosticResult

    alt "diag.status == VERIFIED"
        Note over Caller: proof_ref is non-None — authority bit set
        Caller->>AuditLog: record(proof_ref, developer_fields)
        Caller->>Caller: submit_payment(developer_fields["net_payable"])
    else "diag.status == UNVERIFIABLE"
        Note over Caller: proof_ref is None — decision reached, not proven
        Caller->>Caller: escalate(agent_message, constraint_id)
    else "diag.status == BLOCKED"
        Note over Caller: proof_ref is None — could not attempt verification
        Caller->>Caller: escalate(agent_message, constraint_id)
    end

Loading

%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
sequenceDiagram
    participant Caller
    participant Guard as TDSGuard / InputCreditGuard / GSTGuard
    participant Diag as TaxDiagnosticResult
    participant AuditLog

    Caller->>Guard: calculate_deduction(service, amount)
    Guard-->>Caller: "raw dict {verified, audit_trace, ...}"

    Caller->>Guard: to_diagnostic(raw)
    Guard->>Diag: build(agent_message, developer_fields, proof_ref)
    Guard-->>Caller: diag : TaxDiagnosticResult

    alt "diag.status == VERIFIED"
        Note over Caller: proof_ref is non-None — authority bit set
        Caller->>AuditLog: record(proof_ref, developer_fields)
        Caller->>Caller: submit_payment(developer_fields["net_payable"])
    else "diag.status == UNVERIFIABLE"
        Note over Caller: proof_ref is None — decision reached, not proven
        Caller->>Caller: escalate(agent_message, constraint_id)
    else "diag.status == BLOCKED"
        Note over Caller: proof_ref is None — could not attempt verification
        Caller->>Caller: escalate(agent_message, constraint_id)
    end

Loading

_{Reviews (2): Last reviewed commit: "fix: correct diag.constraint_id access +..." | Re-trigger Greptile}