bigpowers 2.83.3 → 2.84.0

package/.windsurf/rules/survey-context.md

@@ -0,0 +1,135 @@
+---
+name: survey-context
+model: haiku
+description: "Per-task context bootstrap — reads existing specs/ and tech-architecture docs to map the current lifecycle phase and suggest the next skill. Use at the start of any task, when returning after a break, or when unsure what to do next. For deriving a tech-stack doc from scratch, use map-codebase first."
+---
+
+# Survey Context
+
+Read the project's current state and give a phase map + next-skill recommendation. This is the "where am I?" skill — run it at the start of every task.
+
+> **Use this vs map-codebase:** `survey-context` consumes existing specs and docs (fast; does not re-derive). `map-codebase` builds the tech-stack doc from scratch by scanning the codebase. Run `map-codebase` when `specs/tech-architecture/tech-stack.md` doesn't exist yet; run `survey-context` when it does.
+
+> **HARD GATE** — Read specs/ files before suggesting next steps. If state.yaml is stale or contradicts the codebase, request clarification rather than assuming intent.
+
+Orchestrate-project 6 phases: Phase 1 Discover - Phase 2 Elaborate - Phase 3 Plan - Phase 4 Build - Phase 5 Verify - Phase 6 Release
+
+## Process
+
+> **Timing:** `bash scripts/bp-timing.sh start survey-context` at invocation; `bash scripts/bp-timing.sh end survey-context` before handoff.
+
+### 1. Read CONVENTIONS.md
+
+If `CONVENTIONS.md` exists at the project root, read it first. It contains the rules all agents must follow in this project.
+
+### 2. Read specs/ (YAML-first)
+
+Scan the `specs/` directory if it exists:
+
+```
+specs/
+├── state.yaml                  → session: active_flow, epic, git, handoff
+├── release-plan.yaml           → target version, WSJF epic index
+├── execution-status.yaml       → flat story/epic status
+├── planning-status.yaml        → discover-phase checklist (optional)
+├── requirements/
+│   ├── VISION_LATEST.yaml
+│   ├── SCOPE_LATEST.yaml
+│   └── GLOSSARY_LATEST.yaml
+├── plans/                      → TECH_STACK, TEST_PLAN, etc.
+├── epics/                      → eNN shards (flat yaml or eNN/stories/)
+└── bugs/                       → BUG-*.md + registry.yaml
+```
+
+For each YAML file found, note: exists? keys populated? `handoff.next_skill`?
+
+Legacy markdown (`specs/archive/STATE.md`, `RELEASE-PLAN.md`) is **not** SoT if YAML exists.
+
+→ verify: `bash scripts/validate-specs-yaml.sh 2>/dev/null || echo "YAML layout incomplete"`
+
+### 3. Read CLAUDE.md
+
+If `CLAUDE.md` exists at the project root, read it for project context (stack, commands, architecture, conventions).
+
+### 4. Check git state
+
+```bash
+git status --short
+git log --oneline -5
+git branch --show-current
+```
+
+Note: is there a feature branch active? Are there uncommitted changes? Do they match `specs/state.yaml` `git` block?
+
+### 5. Map the lifecycle phase
+
+Based on what you've found, identify which PMBOK phase this project is currently in:
+
+| Phase | Signals |
+|-------|---------|
+| **Discover** | No `requirements/SCOPE_LATEST.yaml` yet, or only rough notes |
+| **Design** | SCOPE exists but no `release-plan.yaml` |
+| **Plan** | `release-plan.yaml` exists; on `main`/`master` branch |
+| **Initiate** | On a feature branch; no code changes yet |
+| **Execute** | `state.yaml` `active_flow: build_epic`; epic capsule in progress |
+| **Verify** | Implementation done; run `verify-work` or `run-evals` |
+| **Bug** | `state.yaml` `active_flow: fix_bug` or open `specs/bugs/BUG-*.md` |
+| **Review** | All code written; no PR yet |
+| **Integrate** | PR open; tests passing |
+| **Sustain** | Ongoing; no active task |
+
+Prefer `specs/state.yaml` `active_flow` and `handoff.next_skill` when present.
+
+### 6. Suggest next skill
+
+Based on the phase and state, recommend the most useful next step:
+
+- **If in Plan/Bug phase and on `main`**: Suggest `kickoff-branch` next.
+- **If in Initiate phase**: Suggest `develop-tdd` or `execute-plan` or `ship-epic`.
+- **If in Execute phase**: Suggest `ship-epic` (resume) or `develop-tdd` for `active_story_id`.
+- **If in Verify phase**: Suggest `verify-work` (UAT) or `run-evals`.
+
+Example:
+```
+Phase: Execute
+Active branch: feat/e02-verify (state.yaml matches)
+release-plan.yaml: v3.0.0, 10 epics
+active_epic_id: e02
+
+Suggested next: ship-epic (resume e02s01 at develop-tdd)
+```
+
+Be specific — name the exact skill and why. If multiple options exist, list them in priority order.
+
+### 7. Surface blockers
+
+If something looks wrong:
+- Broken tests in the baseline
+- Open `specs/bugs/BUG-*.md` with no active fix branch
+- Epic shards missing `verify:` on tasks
+- `validate-specs-yaml.sh` fails
+- Git hash in `state.yaml` stale vs `git rev-parse`
+
+Report blockers first, before recommendations.
+
+### 8. Record story start timestamp
+
+At story start, write `metrics.story_start` with the current ISO 8601 timestamp to `specs/state.yaml` as an **informational progress marker only** — not a measurement input. Cycle-time metrics are now derived from git commit history via `scripts/record-cycle-time.sh` (see `skills/release-branch/REFERENCE.md` §Cycle-time recording).
+
+## Utility outputs
+
+### list-epics (absorbed)
+
+Loop through all `specs/epics/*/epic.yaml` files and print a summary of story counts per epic. Useful for understanding overall project scope and epic distribution.
+
+### check-gates (absorbed)
+
+Print the current `active_flow` from `specs/state.yaml`, run `bash scripts/validate-specs-yaml.sh` to verify YAML integrity, and show `git status` to report uncommitted changes and branch state. Use before handoffs or context transitions.
+
+## Handoff
+
+Gate: READY -> next: plan-work
+Writes: state.yaml handoff.next_skill = plan-work
+
+
+<!-- story: e03s03 -->

package/.windsurf/rules/terse-mode.md

@@ -0,0 +1,42 @@
+---
+name: terse-mode
+model: haiku
+description: "Fallback ultra-compressed communication mode. Cuts token usage ~75% by dropping filler, articles, and pleasantries while keeping full technical accuracy. Use ONLY when context is critically long and compressing output is necessary to continue. Not a strategy — token discipline comes from code shape (small functions, unique names, headless tests), not terser prompts. Use when user says \"caveman mode\", \"terse mode\", \"less tokens\", \"be brief\", or invokes /terse-mode."
+---
+
+Respond terse like smart caveman. All technical substance stay. Only fluff die.
+
+## Persistence
+> **HARD GATE** — **HARD GATE** — Terse mode is for reducing token usage in long sessions. Do NOT use terse mode when clarity is critical (complex design decisions, bug investigations). Enable it only on explicit user request.
+
+
+ACTIVE EVERY RESPONSE once triggered. No revert after many turns. No filler drift. Still active if unsure. Off only when user says "stop" or "normal mode".
+
+## Rules
+
+Drop: articles (a/an/the), filler (just/really/basically/actually/simply), pleasantries (sure/certainly/of course/happy to), hedging. Fragments OK. Short synonyms (big not extensive, fix not "implement a solution for"). Abbreviate common terms (DB/auth/config/req/res/fn/impl). Strip conjunctions. Use arrows for causality (X -> Y). One word when one word enough.
+
+Technical terms stay exact. Code blocks unchanged. Errors quoted exact.
+
+Pattern: `[thing] [action] [reason]. [next step].`
+
+Not: "Sure! I'd be happy to help you with that. The issue you're experiencing is likely caused by..."
+Yes: "Bug in auth middleware. Token expiry check use `<` not `<=`. Fix:"
+
+## Auto-Clarity Exception
+
+Drop terse temporarily for: security warnings, irreversible action confirmations, multi-step sequences where fragment order risks misread, user asks to clarify or repeats question. Resume after clear part done.
+
+Example — destructive op:
+
+> **Warning:** This will permanently delete all rows in the `users` table and cannot be undone.
+>
+> ```sql
+> DROP TABLE users;
+> ```
+>
+> Terse resume. Verify backup exist first.
+
+
+
+<!-- story: e04s02 -->

package/.windsurf/rules/trace-requirement.md

@@ -0,0 +1,69 @@
+---
+name: trace-requirement
+model: haiku
+description: "Link story IDs from specs/release-plan.yaml + epic capsule directories to the implementing code and tests. Produces specs/TRACEABILITY_LATEST.md. Use when you want to verify coverage of a release plan, audit which stories are implemented, or find \"dark\" stories with no code."
+---
+
+# Trace Requirement
+
+Build a traceability matrix from `specs/release-plan.yaml + epic capsule directories` to implementing code and tests. Surfaces gaps in both directions: stories with no code, and code with no story.
+
+## Pre-flight
+
+> **HARD GATE** — `specs/release-plan.yaml + epic capsule directories` must exist. If it doesn't, run `plan-release` first.
+
+→ verify: `[ -f specs/release-plan.yaml + epic capsule directories ] && echo "ready" || echo "BLOCKED: run plan-release first"`
+
+Read `specs/release-plan.yaml + epic capsule directories` fully before proceeding.
+
+## Process
+
+### 1. Extract story IDs
+
+From release-plan.yaml, collect all story IDs (e.g. `1.1`, `1.2`, `2.1`).
+
+→ verify: `grep -o "Story [0-9]\+\.[0-9]\+" specs/release-plan.yaml + epic capsule directories | sort -u`
+
+### 2. Search for story tags in code
+
+Look for `// story: X.Y` or `# story: X.Y` comments in source files and tests:
+
+```
+grep -rn "story: " . --include="*.ts" --include="*.js" --include="*.py" --include="*.sh" | grep -v node_modules
+```
+
+→ verify: `grep -rn "story: " . --include="*.ts" --include="*.sh" | wc -l`
+
+### 3. Build the matrix
+
+For each story ID:
+- **Implemented**: list files that contain `// story: X.Y`
+- **Tested**: list test files that contain `// story: X.Y`
+- **Dark**: story has no tag in any file — flag as unimplemented
+
+For each tagged file with no matching story ID in release-plan.yaml:
+- **Orphan**: code exists but story was removed or never planned — flag for cleanup
+
+### 4. Write specs/TRACEABILITY_LATEST.md
+
+```
+## Story Coverage
+
+| Story | Title              | Files | Tests | Status    |
+|-------|--------------------|-------|-------|-----------|
+| 1.1   | [title]            | 2     | 1     | Covered   |
+| 1.2   | [title]            | 0     | 0     | Dark      |
+
+## Orphan Code (no story tag)
+- [file]: contains untagged implementation
+
+## Gaps (dark stories)
+- Story 1.2: no implementation found → run plan-work
+
+## Coverage summary
+Stories: [X] covered / [Y] dark / [Z] total
+```
+
+→ verify: `grep -c "Covered\|Dark" specs/TRACEABILITY_LATEST.md`
+
+Suggest `plan-work` for each dark story found.

package/.windsurf/rules/using-bigpowers.md

@@ -0,0 +1,111 @@
+---
+name: using-bigpowers
+model: sonnet
+description: "One-time bootstrap that introduces the bigpowers skills system, the PMBOK lifecycle arc, and tells you which skill to call first for your situation. Use when starting with bigpowers for the first time, when user asks \"where do I start?\", or when the skills system needs to be explained."
+---
+
+# Using bigpowers
+> **HARD GATE** — **HARD GATE** — This skill is the entry point. Do NOT skip it when onboarding new users or starting a new session. It establishes the bigpowers methodology, lifecycle phases, and conventions.
+
+
+Welcome to **bigpowers** — a lifecycle of **70** agent skills for production-ready, TDD-driven software by solo developers.
+
+## Install
+
+```bash
+npx bigpowers setup           # one-shot setup
+npm install -g bigpowers       # global install
+bigpowers setup                # sync skills + link to your tools
+```
+
+From source: `git clone` → `bash scripts/install.sh`. Package: [bigpowers on npm](https://www.npmjs.com/package/bigpowers).
+
+**Reach tools:** **Cline** — native AGENTS.md reader (no extension). **Aider** — opt-in `.aider.conf.yml` with `read: AGENTS.md` ([Aider-AI/aider](https://github.com/Aider-AI/aider)). **Codex CLI** — optional `.codex/config.toml` via seed-conventions; global `~/.codex/AGENTS.md` from install.sh.
+
+## What bigpowers is
+
+A curated set of skills organized around the PMBOK developer lifecycle. Each skill does one thing. Skills reference each other by name only — low coupling, high cohesion. All written output goes to `specs/` at your project root.
+
+## The lifecycle at a glance
+
+See orchestrate-project for the canonical 6-phase lifecycle.
+
+```
+BOOTSTRAP   using-bigpowers (this skill, first time only)
+              ↓
+DISCOVER    survey-context → research-first → elaborate-spec
+              ↓
+DESIGN      model-domain / define-language / grill-me / deepen-architecture / design-interface
+              ↓
+PLAN        scope-work → slice-tasks → define-success → plan-work / plan-refactor
+              ↓
+INITIATE    kickoff-branch → guard-git / hook-commits / seed-conventions
+              ↓
+SPIKE?      spike-prototype → (feeds back to plan-work)
+              ↓
+EXECUTE     develop-tdd + enforce-first ←→ delegate-task / dispatch-agents / execute-plan
+              ↓
+VERIFY      run-evals → verify-work
+              ↓
+HARDEN      wire-observability (any phase)
+              ↓
+BUG?        investigate-bug → diagnose-root → validate-fix
+              ↓
+REVIEW      audit-code → request-review → respond-review
+              ↓
+INTEGRATE   commit-message → release-branch
+              ↓
+SUSTAIN     inspect-quality / organize-workspace (ongoing)
+
+UTILITY     terse-mode / craft-skill / edit-document (any phase)
+```
+
+## Where to start
+
+| Your situation | First skill to call |
+|---------------|---------------------|
+| Greenfield project, nothing set up | `seed-conventions` |
+| Existing project, new task | `survey-context` |
+| Vague idea that needs shaping | `elaborate-spec` |
+| Plan exists, ready to implement | `kickoff-branch` → `develop-tdd` |
+| Bug to fix | `investigate-bug` |
+| Code ready for review | `audit-code` |
+| Shipping a feature | `commit-message` → `release-branch` |
+| Solo dev, PRs feel heavy | Enable `profiles/solo-git.md` → `specs/WORKFLOW-solo-git.md` → land via `scripts/land-branch.sh` |
+
+## Solo Git profile
+
+If you work alone and do not want PR ceremony every task:
+
+1. Read [profiles/solo-git.md](../../profiles/solo-git.md).
+2. Register with `compose-workflow` → `specs/WORKFLOW-solo-git.md`.
+3. Ship with `release-branch` in **solo-local** mode (`land-branch.sh`), not `gh pr create`.
+
+You still use worktrees, protected `main`, and verification gates — only the integrate step changes.
+
+## YAML cockpit and dashboard
+
+Operational source of truth:
+
+- `specs/state.yaml` — session, active epic/story, handoff
+- `specs/release-plan.yaml` — release index and epic list
+- `specs/epics/eNN-*.yaml` — stories and tasks with `verify`
+- `specs/execution-status.yaml` — done/pending per story
+
+Start the HTTP dashboard with `visual-dashboard` → `GET /api/status?projectDir=<abs>` and `GET /cockpit.html` for a read-only PM view.
+
+## Key conventions
+
+- **specs/ is your memory.** All domain docs, plans, and investigation outputs go in `specs/` at your project root.
+- **Integrate:** team default is `gh pr` (team-pr); solo profile uses `land-branch.sh`. Never create GitHub issues from skills — use local Markdown files instead.
+- **One skill, one thing.** If you're unsure which skill to call, call `survey-context` — it reads your current state and recommends the next step.
+- **verify: every step.** Every epic task must have `verify: <runnable command>`. Evidence over claims.
+- **The full catalog is auto-generated.** See `SKILL-INDEX.md`; find skills with `search-skills`.
+
+## After this
+
+Call `survey-context` to read your project's current state and get a personalized recommendation for where to go next.
+
+
+
+<!-- story: e03s02 -->

package/.windsurf/rules/validate-contracts.md

@@ -0,0 +1,309 @@
+---
+name: validate-contracts
+model: sonnet
+description: "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."
+---
+
+# Validate Contracts
+
+> **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.
+>
+> **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.
+
+Validate 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.
+
+## Contract types
+
+Three modes of validation:
+
+| Mode | What it catches | When to use |
+|------|----------------|-------------|
+| **Schema** | API response shape mismatches (missing field, wrong type) | Before every deploy, after API changes |
+| **Key-set** | Missing/unexpected keys across two data sources | Translation files, configs, enum definitions |
+| **Shape** | Column type or format violations in data files | After migrations, before consuming exports |
+
+## Contract file convention
+
+All contract files live in `specs/contracts/` and use YAML:
+
+See [REFERENCE.md](REFERENCE.md) for examples.
+
+### 1. API Response Contracts (`--schema`)
+
+Define expected API response shapes and validate live endpoints against them:
+
+See [REFERENCE.md](REFERENCE.md) for examples.
+
+Usage:
+
+```bash
+validate-contracts --schema specs/contracts/users.schema.yaml --url https://api.example.com/users
+# → PASS: /api/users matches expected schema (3/3 fields, types ok)
+# → FAIL: /api/users — field 'email' has type null (expected string)
+```
+
+### 2. Key-Set Contracts (`--key-set`)
+
+Assert that two data sources share a consistent set of keys:
+
+See [REFERENCE.md](REFERENCE.md) for examples.
+
+Usage:
+
+See [REFERENCE.md](REFERENCE.md) for examples.
+
+### 3. Data Shape Contracts (`--shape`)
+
+Validate that a data file matches expected column types and constraints:
+
+See [REFERENCE.md](REFERENCE.md) for examples.
+
+Usage:
+
+See [REFERENCE.md](REFERENCE.md) for examples.
+
+## Process
+
+### 1. Define contract
+
+Create a YAML file in `specs/contracts/` following the schema for the mode.
+
+### 2. Run validation
+
+```bash
+bash scripts/validate-contracts.sh <contract-file>
+```
+
+The runner auto-detects the contract type from the file content (presence of `schema:`,
+`sources:`, or `file:` + `fields:` keys).
+
+### 3. Read the report
+
+Output is JSON Lines (one event per line) plus a human-readable summary:
+
+```
+{"event":"pass","check":"users.schema","detail":"3/3 fields match types"}
+{"event":"warn","check":"users.schema","detail":"field 'avatar' has format: uri (unexpected)"}
+{"event":"fail","check":"i18n-keys","detail":"missing: 2 keys in target"}
+```
+
+Final summary:
+
+```
+=== Validate Contracts Summary ===
+Schema: 3/3 pass | Key-set: 1/1 fail | Shape: 2/2 pass
+FAILED: 1 contract has divergence
+```
+
+### 4. Fix divergence
+
+- **Missing keys** → add to target source
+- **Type mismatches** → update schema or fix producer
+- **Shape violations** → fix migration or consumer
+
+### 5. Re-validate
+
+```bash
+bash scripts/validate-contracts.sh <contract-file>
+# → All pass → ready to deploy
+```
+
+---
+
+# Validate Contracts — Reference
+
+## Navigation
+
+| Lines | Section |
+|-------|---------|
+| 1 | Title |
+| 3–14 | Navigation |
+| 16–24 | Integration |
+| 26–35 | Configuration |
+| 37–46 | Verification |
+| 48–170 | Reference blocks + Examples 1–6 |
+| 172–190 | Integration (duplicate) + Configuration + Verification |
+
+## Integration
+
+- **Pre-deploy gate:** The `deploy` skill runs `validate-contracts` before smoke-test.
+- **CI pipeline:** JSON Lines output is CI-friendly; pipe to `jq` for assertions.
+- **Pre-migration:** Run `validate-contracts --shape` before consuming migration output.
+
+
+---
+
+## Configuration
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `CONTRACTS_DIR` | `specs/contracts/` | Directory containing contract YAML files |
+| `VALIDATE_ALL` | `false` | If true, run all contracts in the directory |
+| `STRICT_MODE` | `false` | Treat warnings as failures |
+| `OUTPUT_FORMAT` | `text` | `text` or `json` |
+
+
+---
+
+## Verification
+
+→ verify: `test -f validate-contracts/SKILL.md && grep -q 'name: validate-contracts' validate-contracts/SKILL.md && echo OK`
+→ verify: `grep -qi 'specs/contracts\|JSON Schema\|key.set\|data.shape' validate-contracts/SKILL.md && echo OK`
+→ verify: `grep -ci 'divergence\|missing key\|type mismatch\|diff\|conforms\|column' validate-contracts/SKILL.md | awk '{if($1>=3) print "OK"; else print "FAIL"}'`
+→ 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"}'`
+→ verify: `grep -q 'validate-contracts' SKILL-INDEX.md && echo OK`
+
+---
+
+## Reference block 1
+
+```yaml
+# specs/contracts/users.schema.yaml
+endpoint: /api/users
+method: GET
+schema:
+  type: object
+  required: [id, name, email]
+  properties:
+    id: { type: number }
+    name: { type: string }
+    email: { type: string, format: email }
+```
+
+---
+
+## Reference block 2
+
+```yaml
+# specs/contracts/migration-output.yaml
+file: data/users-export.json
+format: json
+fields:
+  - name: user_id
+    type: number
+    required: true
+  - name: full_name
+    type: string
+    required: true
+  - name: created_at
+    type: string
+    format: date-time
+    required: false
+```
+
+---
+
+## Example 1
+
+```
+specs/contracts/
+├── users.schema.yaml        # API response schema
+├── i18n-keys.yaml           # Key-set comparison
+├── migration-output.yaml    # Data shape contract
+└── README.md                # Local conventions
+```
+
+---
+
+## Example 2
+
+```yaml
+# specs/contracts/users.schema.yaml
+endpoint: /api/users
+method: GET
+schema:
+  type: object
+  required: [id, name, email]
+  properties:
+    id: { type: number }
+    name: { type: string }
+    email: { type: string, format: email }
+```
+
+---
+
+## Example 3
+
+```yaml
+# specs/contracts/i18n-keys.yaml
+sources:
+  reference: src/frontend/locales/en.json
+  target: src/backend/messages/en.json
+mode: subset      # all target keys must exist in reference
+```
+
+---
+
+## Example 4
+
+```bash
+validate-contracts --key-set specs/contracts/i18n-keys.yaml
+# → missing: 2 keys in reference not found in target: ['settings.privacy', 'help.faq']
+# → added: 1 key in target not in reference: ['deprecated.field']
+# → exit 1 (divergence)
+```
+
+---
+
+## Example 5
+
+```yaml
+# specs/contracts/migration-output.yaml
+file: data/users-export.json
+format: json
+fields:
+  - name: user_id
+    type: number
+    required: true
+  - name: full_name
+    type: string
+    required: true
+  - name: created_at
+    type: string
+    format: date-time
+    required: false
+```
+
+---
+
+## Example 6
+
+```bash
+validate-contracts --shape specs/contracts/migration-output.yaml
+# → PASS: 3/3 fields validated, 5000 rows OK
+# → WARN: field 'full_name' has 12 null values (0.24%)
+# → FAIL: field 'user_id' has 3 rows with type string (expected number)
+```
+
+---
+
+## Integration
+
+- **Pre-deploy gate:** The `deploy` skill runs `validate-contracts` before smoke-test.
+- **CI pipeline:** JSON Lines output is CI-friendly; pipe to `jq` for assertions.
+- **Pre-migration:** Run `validate-contracts --shape` before consuming migration output.
+
+
+---
+
+## Configuration
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `CONTRACTS_DIR` | `specs/contracts/` | Directory containing contract YAML files |
+| `VALIDATE_ALL` | `false` | If true, run all contracts in the directory |
+| `STRICT_MODE` | `false` | Treat warnings as failures |
+| `OUTPUT_FORMAT` | `text` | `text` or `json` |
+
+
+---
+
+## Verification
+
+→ verify: `test -f validate-contracts/SKILL.md && grep -q 'name: validate-contracts' validate-contracts/SKILL.md && echo OK`
+→ verify: `grep -qi 'specs/contracts\|JSON Schema\|key.set\|data.shape' validate-contracts/SKILL.md && echo OK`
+→ verify: `grep -ci 'divergence\|missing key\|type mismatch\|diff\|conforms\|column' validate-contracts/SKILL.md | awk '{if($1>=3) print "OK"; else print "FAIL"}'`
+→ 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"}'`
+→ verify: `grep -q 'validate-contracts' SKILL-INDEX.md && echo OK`