Cursor rule

1---
2description: "Assert data shape consistency across system boundaries — live API responses against JSON Schema, key-set comparison across layers, data shape validation for migrations and exports. Catches silent data corruption before deploy."
3alwaysApply: false
4---
5 
6# Validate Contracts
7 
8> **HARD GATE** — Do NOT deploy or migrate data without running `validate-contracts` first. Silent data divergence between system boundaries causes the hardest-to-debug production bugs.
9>
10> **HARD GATE** — Contract files MUST be version-controlled alongside code. Outdated contracts are worse than no contracts. If a contract hasn't been reviewed in 30 days, flag it as stale.
11 
12Validate that data structures stay in sync across system boundaries — front-end vs back-end, API responses vs expected schemas, config files vs code assumptions, migration output vs target shape.
13 
14## Contract types
15 
16| Mode | What it catches | When to use |
17|------|----------------|-------------|
18| **Schema** | API response shape mismatches | Before every deploy, after API changes |
19| **Key-set** | Missing/unexpected keys across two data sources | Translation files, configs, enum definitions |
20| **Shape** | Column type or format violations | After migrations, before consuming exports |
21 
22## Contract file convention
23 
24All contract files live in `specs/contracts/` as YAML. See [REFERENCE.md](REFERENCE.md) for extended examples.
25 
26### Key-set example
27 
28```yaml
29# specs/contracts/i18n-keys.yaml
30sources:
31  reference: src/locales/en.json
32  target: src/messages/en.json
33mode: subset
34```
35 
36## Process
37 
38### 1. Define contract
39 
40Create a YAML file in `specs/contracts/` following the schema for the mode.
41 
42### 2. Run validation
43 
44```bash
45bash scripts/validate-contracts.sh specs/contracts/<contract>.yaml
46```
47 
48The runner auto-detects key-set contracts (`sources:` block). Schema and shape modes are documented in REFERENCE.md for consumer projects.
49 
50### 3. Read the report
51 
52```
53PASS: key-set contract
54# or
55FAIL: key-set — N keys in reference missing from target
56```
57 
58JSON Lines output for CI is planned for schema/shape modes; key-set failures exit non-zero.
59 
60### 4. Fix divergence
61 
62- **Missing keys** → add to target source
63- **Type mismatches** → update schema or fix producer
64- **Shape violations** → fix migration or consumer
65 
66### 5. Re-validate
67 
68```bash
69bash scripts/validate-contracts.sh specs/contracts/<contract>.yaml
70```
71 
72## Verify arc
73 
74Part of **★ VERIFY ★**: `verify-work` → `validate-contracts` → `smoke-test` → `run-evals` → `audit-code`
75 
76## Verify
77 
78→ verify: `test -x scripts/validate-contracts.sh && bash scripts/validate-contracts.sh --self-test && grep -q 'validate-contracts.sh' skills/validate-contracts/SKILL.md && echo OK`
79 
80---
81 
82# Validate Contracts — Reference
83 
84## Navigation
85 
86| Lines | Section |
87|-------|---------|
88| 1 | Title |
89| 3–23 | Navigation |
90| 24–32 | Integration |
91| 33–44 | Configuration |
92| 45–54 | Verification |
93| 55–71 | Reference block 1 |
94| 72–92 | Reference block 2 |
95| 93–104 | Example 1 |
96| 105–121 | Example 2 |
97| 122–133 | Example 3 |
98| 134–144 | Example 4 |
99| 145–165 | Example 5 |
100| 166–176 | Example 6 |
101| 177–185 | Integration |
102| 186–197 | Configuration |
103| 198–204 | Verification |
104 
105## Integration
106 
107- **Pre-deploy gate:** The `deploy` skill runs `validate-contracts` before smoke-test.
108- **CI pipeline:** JSON Lines output is CI-friendly; pipe to `jq` for assertions.
109- **Pre-migration:** Run `validate-contracts --shape` before consuming migration output.
110 
111 
112---
113 
114## Configuration
115 
116| Variable | Default | Description |
117|----------|---------|-------------|
118| `CONTRACTS_DIR` | `specs/contracts/` | Directory containing contract YAML files |
119| `VALIDATE_ALL` | `false` | If true, run all contracts in the directory |
120| `STRICT_MODE` | `false` | Treat warnings as failures |
121| `OUTPUT_FORMAT` | `text` | `text` or `json` |
122 
123 
124---
125 
126## Verification
127 
128→ verify: `test -f validate-contracts/SKILL.md && grep -q 'name: validate-contracts' validate-contracts/SKILL.md && echo OK`
129→ verify: `grep -qi 'specs/contracts\|JSON Schema\|key.set\|data.shape' validate-contracts/SKILL.md && echo OK`
130→ verify: `grep -ci 'divergence\|missing key\|type mismatch\|diff\|conforms\|column' validate-contracts/SKILL.md | awk '{if($1>=3) print "OK"; else print "FAIL"}'`
131→ verify: `grep -ci 'JSON Lines\|machine.parse\|CI\|deploy.*gate\|pre.deploy' validate-contracts/SKILL.md | awk '{if($1>=2) print "OK"; else print "FAIL"}'`
132→ verify: `grep -q 'validate-contracts' SKILL-INDEX.md && echo OK`
133 
134---
135 
136## Reference block 1
137 
138```yaml
139# specs/contracts/users.schema.yaml
140endpoint: /api/users
141method: GET
142schema:
143  type: object
144  required: [id, name, email]
145  properties:
146    id: { type: number }
147    name: { type: string }
148    email: { type: string, format: email }
149```
150 
151---
152 
153## Reference block 2
154 
155```yaml
156# specs/contracts/migration-output.yaml
157file: data/users-export.json
158format: json
159fields:
160  - name: user_id
161    type: number
162    required: true
163  - name: full_name
164    type: string
165    required: true
166  - name: created_at
167    type: string
168    format: date-time
169    required: false
170```
171 
172---
173 
174## Example 1
175 
176```
177specs/contracts/
178├── users.schema.yaml        # API response schema
179├── i18n-keys.yaml           # Key-set comparison
180├── migration-output.yaml    # Data shape contract
181└── README.md                # Local conventions
182```
183 
184---
185 
186## Example 2
187 
188```yaml
189# specs/contracts/users.schema.yaml
190endpoint: /api/users
191method: GET
192schema:
193  type: object
194  required: [id, name, email]
195  properties:
196    id: { type: number }
197    name: { type: string }
198    email: { type: string, format: email }
199```
200 
201---
202 
203## Example 3
204 
205```yaml
206# specs/contracts/i18n-keys.yaml
207sources:
208  reference: src/frontend/locales/en.json
209  target: src/backend/messages/en.json
210mode: subset      # all target keys must exist in reference
211```
212 
213---
214 
215## Example 4
216 
217```bash
218validate-contracts --key-set specs/contracts/i18n-keys.yaml
219# → missing: 2 keys in reference not found in target: ['settings.privacy', 'help.faq']
220# → added: 1 key in target not in reference: ['deprecated.field']
221# → exit 1 (divergence)
222```
223 
224---
225 
226## Example 5
227 
228```yaml
229# specs/contracts/migration-output.yaml
230file: data/users-export.json
231format: json
232fields:
233  - name: user_id
234    type: number
235    required: true
236  - name: full_name
237    type: string
238    required: true
239  - name: created_at
240    type: string
241    format: date-time
242    required: false
243```
244 
245---
246 
247## Example 6
248 
249```bash
250validate-contracts --shape specs/contracts/migration-output.yaml
251# → PASS: 3/3 fields validated, 5000 rows OK
252# → WARN: field 'full_name' has 12 null values (0.24%)
253# → FAIL: field 'user_id' has 3 rows with type string (expected number)
254```
255 
256---
257 
258## Integration
259 
260- **Pre-deploy gate:** The `deploy` skill runs `validate-contracts` before smoke-test.
261- **CI pipeline:** JSON Lines output is CI-friendly; pipe to `jq` for assertions.
262- **Pre-migration:** Run `validate-contracts --shape` before consuming migration output.
263 
264 
265---
266 
267## Configuration
268 
269| Variable | Default | Description |
270|----------|---------|-------------|
271| `CONTRACTS_DIR` | `specs/contracts/` | Directory containing contract YAML files |
272| `VALIDATE_ALL` | `false` | If true, run all contracts in the directory |
273| `STRICT_MODE` | `false` | Treat warnings as failures |
274| `OUTPUT_FORMAT` | `text` | `text` or `json` |
275 
276 
277---
278 
279## Verification
280 
281→ verify: `test -f validate-contracts/SKILL.md && grep -q 'name: validate-contracts' validate-contracts/SKILL.md && echo OK`
282→ verify: `grep -qi 'specs/contracts\|JSON Schema\|key.set\|data.shape' validate-contracts/SKILL.md && echo OK`
283→ verify: `grep -ci 'divergence\|missing key\|type mismatch\|diff\|conforms\|column' validate-contracts/SKILL.md | awk '{if($1>=3) print "OK"; else print "FAIL"}'`
284→ verify: `grep -ci 'JSON Lines\|machine.parse\|CI\|deploy.*gate\|pre.deploy' validate-contracts/SKILL.md | awk '{if($1>=2) print "OK"; else print "FAIL"}'`
285→ verify: `grep -q 'validate-contracts' SKILL-INDEX.md && echo OK`
286