data-model-verification · diff
git:20260624.6ebd21c to git:20260624.db13361
36 added, 8 removed. Audit A to A.
---
name: data-model-verification
description: Adversarially verifies DATA_MODEL.md property rows against cited Source files. Use after data-model-documenter when DATA_MODEL.md changed — inventories each property in added/changed catalog sections and classifies VERIFIED / REFUTED / UNVERIFIABLE. Triggers on "verify DATA_MODEL", "check catalog against source", "data model verification".
when_to_use: |
Use in Wave 2 of the gate DAG after `data-model-documenter`, when `DATA_MODEL.md` has new or changed `###` sections. The load-bearing signal: downstream agents may treat the catalog as ground truth — hallucinated properties must be caught before ship-ready.
Not when: `DATA_MODEL.md` did not change, or only the changelog/header changed with no catalog section edits. Not when the task is authoring the catalog — use `data-model-documentation`. Not for general code review — use `code-reviewer`.
compatibility: Requires Bash. Works in Claude Code and Cursor via install.sh / install-cursor.sh. Read-only — never writes `DATA_MODEL.md`.
---
# Data Model Verification
Gate node **`G-data-verify`** ([gate-dag.md](../../references/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.
- ## Protocol
+ ## 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:
+
+ ```sh
+ PROJ="${CURSOR_PROJECT_DIR:-${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:
+
+ ```sh
+ 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](https://github.com/LazyIsEfficient/agentic-os/issues/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](assets/report-template.md)
## Tier discipline
Tier definitions: review-tiers (`.claude/rules/review-tiers.md` or `.cursor/rules/review-tiers.mdc`) — stochastic judgment proposes, deterministic verification disposes.
- - **REFUTED** without `file:line` quote or grep evidence is not REFUTED — downgrade to UNVERIFIABLE
- - **hold** verdict only when REFUTED > 0 (Tier 1)
- - UNVERIFIABLE counts are advisory; log recurring patterns to [findings-ledger](../findings-ledger/SKILL.md) for ratchet (Tier 0 extractors — [#194](https://github.com/LazyIsEfficient/agentic-os/issues/194))
-
- ## Future: deterministic extractors
-
- When stack-specific scripts exist (`scripts/extract-data-model/`), prefer their output over manual reading. Until then, quote-based verification is Tier 1.
+ - **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](../findings-ledger/SKILL.md) 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](../data-model-documentation/SKILL.md) — catalog format and merge rules (author skill)
- [data-model-verifier](../../agents/data-model-verifier.md) — agent that executes this protocol