git:20260713.e86d282 to git:20260716.7c29779

---

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`.

---

# 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.

## 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="${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`) — 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](../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