# template_data_descriptor - AGENTS.md

## Ground truth

Configuration lives in `manuscript/config.yaml`; the machine-readable descriptor lives in `data/example_descriptor.json`; public synthetic fixture bytes live in `data/fixtures/`; reusable validation, verification, and figure-data logic lives in `src/data_descriptor/` (`descriptor.py`, `verification.py`, `figures.py`). Manuscript figures under `manuscript/figures/`, their provenance registry under `output/figures/figure_registry.json`, and release artifacts under `output/reports/` are regenerated by `scripts/generate_figures.py` and `scripts/generate_release_artifacts.py` and must not be hand-edited.

## Commands

Run tests from the monorepo root:

```bash
uv run pytest projects/templates/template_data_descriptor/tests --cov=projects/templates/template_data_descriptor/src --cov-fail-under=90
uv run python scripts/pipeline/stage_01_test.py --project templates/template_data_descriptor --project-only
uv run python scripts/pipeline/stage_04_validate.py --project templates/template_data_descriptor
```

## Contracts and boundaries

Keep scripts thin: `generate_figures.py` and `generate_release_artifacts.py` only plot/serialize and print paths. Business logic belongs in `src/data_descriptor/`; tests use real fixture descriptors and real temporary files (no mocks). Publication claims must stay bound to descriptor validity, schema completeness, field constraints, provenance depth, license state, byte-level checksum verification, metadata-only release manifests, and reproducibility TODO evidence — never to empirical effects in the synthetic demonstration data.

Decision memory and verifier hardening follow [`docs/rules/memory_and_decision_records.md`](../../../docs/rules/memory_and_decision_records.md): keep volatile numbers generated (not transcribed into prose), use `WHY:` comments only for surprising local choices, and pair every verifier-like gate (validation, checksum verification) with a negative control — as `demo_broken_descriptor()` and the `test_verification.py` mismatch cases do.