aiwg
Version:
Cognitive architecture for AI-augmented software development with structured memory, ensemble validation, and closed-loop correction. FAIR-aligned artifacts, 84% cost reduction via human-in-the-loop, standards adopted by 100+ organizations.
298 lines (266 loc) • 6.99 kB
YAML
# 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"