Windsurf rules

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