# Citation Audit Schema
# Based on REF-059 LitLLM (hallucination detection)
# Issues: #107, #119

$schema: "https://json-schema.org/draft/2020-12/schema"
$id: "https://aiwg.io/schemas/citation-audit/v1"
title: "Citation Audit Schema"
description: |
  Schema for citation verification and hallucination detection.
  Verifies all citations point to real research documents.

type: object
required:
  - audit_id
  - target
  - citations
  - summary

properties:
  audit_id:
    type: string
    format: uuid
    description: "Unique audit identifier"

  timestamp:
    type: string
    format: date-time

  target:
    type: object
    required: [path]
    properties:
      path:
        type: string
        description: "File being audited"
      hash:
        type: string
        description: "SHA-256 of file content"
    description: "Target file information"

  citations:
    type: array
    items:
      $ref: "#/$defs/Citation"
    description: "All citations found in target"

  summary:
    type: object
    required:
      - total
      - verified
      - hallucinated
      - confidence
    properties:
      total:
        type: integer
        minimum: 0
      verified:
        type: integer
        minimum: 0
      hallucinated:
        type: integer
        minimum: 0
      malformed:
        type: integer
        minimum: 0
      unreachable:
        type: integer
        minimum: 0
      inconsistent:
        type: integer
        minimum: 0
      confidence:
        type: number
        minimum: 0
        maximum: 1
        description: "verified / total"
    description: "Audit summary statistics"

$defs:
  Citation:
    type: object
    required:
      - ref_id
      - status
    properties:
      ref_id:
        type: string
        pattern: "^REF-[0-9]{3}(-[a-z]+)?$"
        description: "Reference identifier"

      line_number:
        type: integer
        description: "Line where citation appears"

      context:
        type: string
        description: "Surrounding text"

      status:
        type: string
        enum:
          - verified         # Citation verified against corpus
          - hallucinated     # No matching file found
          - malformed        # Invalid REF-XXX format
          - unreachable      # File exists but path broken
          - inconsistent     # Metadata mismatch
        description: "Verification status"

      verification:
        type: object
        properties:
          file_exists:
            type: boolean
          file_path:
            type: string
          doi_valid:
            type: boolean
          metadata_match:
            type: boolean
          page_numbers:
            type: boolean
            description: "Page numbers present for quotes"
        description: "Verification details"

      issues:
        type: array
        items:
          type: object
          properties:
            type:
              type: string
              enum:
                - missing_file
                - invalid_format
                - broken_path
                - metadata_mismatch
                - missing_doi
                - missing_page_number
            severity:
              type: string
              enum: [error, warning, info]
            message:
              type: string
            suggestion:
              type: string
        description: "Issues found with this citation"

# Verification rules
verification_rules:
  required_for_quotes:
    - page_numbers
    - doi_or_url

  format_validation:
    - pattern: "^REF-[0-9]{3}(-[a-z]+)?$"
      message: "Invalid REF format"

  file_check:
    locations:
      - ".aiwg/research/findings/"
      - ".aiwg/research/paper-analysis/"
      - "docs/references/"

  doi_validation:
    enabled: true
    api: "https://doi.org/api/handles/"
    timeout_ms: 5000

# Detection categories
detection_categories:
  hallucination:
    description: "Citation to non-existent paper"
    severity: error
    indicators:
      - no_matching_file
      - invalid_doi
      - no_corpus_entry

  fabrication:
    description: "Made-up reference details"
    severity: error
    indicators:
      - doi_not_found
      - author_mismatch
      - title_not_found

  misattribution:
    description: "Correct paper, wrong details"
    severity: warning
    indicators:
      - metadata_mismatch
      - year_discrepancy
      - venue_mismatch

  incomplete:
    description: "Missing required information"
    severity: warning
    indicators:
      - missing_page_for_quote
      - missing_doi
      - incomplete_metadata

# Output formats
output_formats:
  text:
    template: |
      Citation Audit Report
      =====================
      File: {{target.path}}
      Date: {{timestamp}}

      Results:
      {{#each citations}}
      {{status_icon status}} {{ref_id}} {{#if title}}({{title}}){{/if}}
        {{#each issues}}
        - {{severity}}: {{message}}
        {{/each}}
      {{/each}}

      Summary:
      - Total: {{summary.total}}
      - Verified: {{summary.verified}}
      - Hallucinated: {{summary.hallucinated}}
      - Confidence: {{format_percent summary.confidence}}

  json:
    description: "Full structured audit report"

  sarif:
    description: "SARIF format for IDE integration"

# Agent integration
agent_protocol:
  pre_commit:
    description: "Run audit before committing"
    on_hallucination: block_commit
    on_warning: warn_user

  on_generation:
    description: "Audit generated content"
    trigger: after_write
    target_patterns: ["**/*.md"]

  citation_rules:
    - rule: "All REF-XXX must exist"
      action: error
    - rule: "Quotes must have page numbers"
      action: warning
    - rule: "Published papers must have DOI"
      action: warning

# Examples
examples:
  - audit_id: "audit-001-example"
    timestamp: "2026-01-25T15:00:00Z"
    target:
      path: "docs/architecture/sad.md"
      hash: "abc123..."
    citations:
      - ref_id: "REF-056"
        line_number: 42
        context: "Following FAIR principles (REF-056)..."
        status: verified
        verification:
          file_exists: true
          file_path: ".aiwg/research/findings/REF-056-fair-principles.md"
          doi_valid: true
          metadata_match: true
      - ref_id: "REF-999"
        line_number: 87
        context: "As shown in REF-999..."
        status: hallucinated
        issues:
          - type: missing_file
            severity: error
            message: "No file found for REF-999"
            suggestion: "Remove citation or add paper to corpus"
    summary:
      total: 2
      verified: 1
      hallucinated: 1
      malformed: 0
      unreachable: 0
      inconsistent: 0
      confidence: 0.5

# References
references:
  research:
    - "@.aiwg/research/findings/REF-059-litllm.md"
  implementation:
    - "#107"
    - "#119"
  related:
    - "@.claude/rules/citation-policy.md"
    - "@agentic/code/frameworks/sdlc-complete/schemas/research/frontmatter-schema.yaml"