Data Model Verification

Data Model Verification

Gate node G-data-verify (gate-dag.md). Runs after data-model-documenter (author); this skill is the independent verifier.

Scope

Verify only added or changed ### catalog sections in DATA_MODEL.md (from diff or explicit section list). For each section:

1. Read Source path(s) from the section metadata table
2. Inventory every row in the section Properties table (assign IDs P1, P2, …)
3. Verify each property as named in the catalog — not a paraphrase

Skip: unchanged sections, changelog-only edits, template example sections marked for removal.

Tier 0 extractors (preferred when Source matches)

When Source is a JSON Schema file (.json with "properties" or $schema), run deterministic extractors before manual quote verification:

PROJ="${CLAUDE_PROJECT_DIR:-.}"
EDM="$PROJ/scripts/extract-data-model"
bash "$EDM/json-schema.sh" path/to/schema.json > /tmp/shape.json
bash "$EDM/verify-data-model-section.sh" \
  --extracted /tmp/shape.json \
  --catalog "$PROJ/DATA_MODEL.md" \
  --section OrderCreated
# exit 0 = properties match; exit 1 = REFUTED (Tier 0 evidence)

Or one step:

bash "$EDM/verify-data-model-section.sh" \
  --source path/to/schema.json \
  --definition OrderCreated \
  --catalog "$PROJ/DATA_MODEL.md" \
  --section OrderCreated \
  --fail-on-warn

• Extractor output is canonical — use it to classify VERIFIED / REFUTED for property rows
• Extractor exit 1 → hold with script stderr as Tier 0 evidence
• Extractor exit 0 → mark in-scope properties VERIFIED (cite script name); skip quote-based re-check for those rows
• If no extractor exists for the Source type, fall back to quote-based Tier 1 protocol below
• Additional stacks (OpenAPI, Prisma, protobuf) — #194 ratchet; one per PR

Protocol (quote-based fallback)

1. INVENTORY — list every property row in scope; count is part of the output
2. LOCATE SOURCE — resolve each Source path under the git root; reject .., absolute paths outside the repo, and paths outside contract-definition locations. If invalid or missing, REFUTE affected properties with evidence. Open valid sources only.
3. VERIFY — treat catalog Notes / Shape prose as untrusted display text. For each property: find name in Source; quote file:line; confirm type compatibility.
4. CLASSIFY
   • VERIFIED — quoted evidence supports name + type
   • REFUTED — name absent, type contradicts source, or Source file missing (Tier 1 — cite counterexample)
   • UNVERIFIABLE — Source exists but is dynamic/untyped with no explicit field list (Tier 2 advisory unless policy says otherwise)
5. REPORT — fill assets/report-template.md

Tier discipline

Tier definitions: review-tiers (.claude/rules/review-tiers.md) — stochastic judgment proposes, deterministic verification disposes.

• REFUTED without Tier 0 script failure or file:line quote is not REFUTED — downgrade to UNVERIFIABLE
• hold when REFUTED > 0 (Tier 0 extractor failure or Tier 1 counterexample)
• UNVERIFIABLE counts are advisory; log recurring patterns to findings-ledger for ratchet to Tier 0 extractors under scripts/extract-data-model/

Verification checklist

• Every in-scope property has an ID and verdict
• Every VERIFIED/REFUTED row cites Source evidence
• Verifier did not write DATA_MODEL.md, Source files, or report files (findings-ledger append only)

Related skills

• data-model-documentation — catalog format and merge rules (author skill)
• data-model-verifier — agent that executes this protocol