bigpowers 2.12.1 → 2.14.0

package/.pi/package.json

@@ -1,7 +1,7 @@
 {
   "name": "bigpowers",
-  "version": "2.12.1",
-  "description": "66 skills — 61 agent skills for spec-driven, test-first software development by solo developers",
+  "version": "2.14.0",
+  "description": "67 skills — 61 agent skills for spec-driven, test-first software development by solo developers",
   "keywords": [
     "pi-package"
   ],

package/.pi/prompts/audit-code.md

@@ -15,6 +15,7 @@ Run this self-review before asking anyone else to look at the code. The goal is
 
 - Default: full checklist
 - --quick: Run only Supply Chain and Test Coverage. Use for changes under 50 LOC.
+- --gate: Non-interactive mode for automated CI gating (used by build-epic step 6). Exit with non-zero status code (`exit 1`) on ANY checklist failure; `exit 0` only if ALL items pass. Produces a compact pass/fail summary to stderr. On failure, list every ✗ item with reason.
 
 ## Checklist
 
@@ -104,6 +105,19 @@ Report the checklist with ✓ / ✗ per item. For each ✗, describe what needs
 If all items pass: suggest running `request-review` for an independent second opinion.
 If any items fail: fix them before proceeding.
 
+### Gate mode output (`--gate`)
+
+In `--gate` mode, print one summary line per checklist section:
+
+```
+PASS Supply Chain & Security
+FAIL Provenance & Metadata (2 items)
+PASS Law of Demeter
+...
+```
+
+Aggregate exit code: `0` if all sections PASS, `1` (non-zero) if any section FAILs. Write the full audit report to `specs/verifications/AUDIT-<epic>-<story>.md` as a permanent record.
+
 ## Handoff
 
 Gate: READY -> next: commit-message

package/.pi/prompts/build-epic.md

@@ -22,7 +22,7 @@ Orchestrates the **build** flow for a single epic: survey → plan tasks → kic
 | 3 | `kickoff-branch` — feature branch + clean baseline |
 | 4 | `develop-tdd` — red-green per task |
 | 5 | `verify-work` — UAT + mechanical gates |
-| 6 | `audit-code` — self-review checklist |
+| 6 | `audit-code` — **non-optional gate** (pass/fail; fail → loop back to step 4) |
 | 7 | `commit-message` — Conventional Commits draft |
 | 8 | `release-branch` — PR or solo land |
 
@@ -35,6 +35,15 @@ Orchestrates the **build** flow for a single epic: survey → plan tasks → kic
 5. After step verify passes, increment `epic_cycle.step` in `state.yaml` (or `bash scripts/bp-yaml-set.sh` if available).
 6. On story complete, set `execution-status.yaml` story key to `done`; run `bash scripts/sync-status-from-epics.sh`.
 
+### Step 6 — audit-code gate (non-optional)
+
+After step 5 (verify-work) completes successfully, step 6 runs `audit-code` automatically in `--gate` mode:
+
+1. **Run audit:** Invoke `audit-code --gate` on the complete diff for this story.
+2. **Pass (exit 0):** All checklist sections pass → advance to step 7 (commit-message). Record `epic_cycle.audit_result: pass` in `state.yaml`.
+3. **Fail (exit 1):** One or more checklist sections fail → **reset `epic_cycle.current_step` to `4`** (develop-tdd) and add the failing section IDs to `completed_steps` as `"1,2,3,4,5,6(fail: ...)"`. Record `epic_cycle.audit_result: fail` in `state.yaml`. Do NOT advance past step 6 until audit passes.
+4. **Audit artifact:** Full audit report saved to `specs/verifications/AUDIT-<epic>-<story>.md` regardless of pass/fail, for reviewer traceability.
+
 ## Handoff
 
 Write `handoff.next_skill` and `handoff.context` in `state.yaml` when pausing mid-epic.

package/.pi/prompts/validate-contracts.md

@@ -0,0 +1,181 @@
+---
+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:
+
+```
+specs/contracts/
+├── users.schema.yaml        # API response schema
+├── i18n-keys.yaml           # Key-set comparison
+├── migration-output.yaml    # Data shape contract
+└── README.md                # Local conventions
+```
+
+### 1. API Response Contracts (`--schema`)
+
+Define expected API response shapes and validate live endpoints against them:
+
+```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 }
+```
+
+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:
+
+```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
+```
+
+Usage:
+
+```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)
+```
+
+### 3. Data Shape Contracts (`--shape`)
+
+Validate that a data file matches expected column types and constraints:
+
+```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
+```
+
+Usage:
+
+```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)
+```
+
+## 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
+```
+
+## 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`

package/.pi/skills/audit-code/SKILL.md

@@ -17,6 +17,7 @@ Run this self-review before asking anyone else to look at the code. The goal is
 
 - Default: full checklist
 - --quick: Run only Supply Chain and Test Coverage. Use for changes under 50 LOC.
+- --gate: Non-interactive mode for automated CI gating (used by build-epic step 6). Exit with non-zero status code (`exit 1`) on ANY checklist failure; `exit 0` only if ALL items pass. Produces a compact pass/fail summary to stderr. On failure, list every ✗ item with reason.
 
 ## Checklist
 
@@ -106,6 +107,19 @@ Report the checklist with ✓ / ✗ per item. For each ✗, describe what needs
 If all items pass: suggest running `request-review` for an independent second opinion.
 If any items fail: fix them before proceeding.
 
+### Gate mode output (`--gate`)
+
+In `--gate` mode, print one summary line per checklist section:
+
+```
+PASS Supply Chain & Security
+FAIL Provenance & Metadata (2 items)
+PASS Law of Demeter
+...
+```
+
+Aggregate exit code: `0` if all sections PASS, `1` (non-zero) if any section FAILs. Write the full audit report to `specs/verifications/AUDIT-<epic>-<story>.md` as a permanent record.
+
 ## Handoff
 
 Gate: READY -> next: commit-message

package/.pi/skills/build-epic/SKILL.md

@@ -24,7 +24,7 @@ Orchestrates the **build** flow for a single epic: survey → plan tasks → kic
 | 3 | `kickoff-branch` — feature branch + clean baseline |
 | 4 | `develop-tdd` — red-green per task |
 | 5 | `verify-work` — UAT + mechanical gates |
-| 6 | `audit-code` — self-review checklist |
+| 6 | `audit-code` — **non-optional gate** (pass/fail; fail → loop back to step 4) |
 | 7 | `commit-message` — Conventional Commits draft |
 | 8 | `release-branch` — PR or solo land |
 
@@ -37,6 +37,15 @@ Orchestrates the **build** flow for a single epic: survey → plan tasks → kic
 5. After step verify passes, increment `epic_cycle.step` in `state.yaml` (or `bash scripts/bp-yaml-set.sh` if available).
 6. On story complete, set `execution-status.yaml` story key to `done`; run `bash scripts/sync-status-from-epics.sh`.
 
+### Step 6 — audit-code gate (non-optional)
+
+After step 5 (verify-work) completes successfully, step 6 runs `audit-code` automatically in `--gate` mode:
+
+1. **Run audit:** Invoke `audit-code --gate` on the complete diff for this story.
+2. **Pass (exit 0):** All checklist sections pass → advance to step 7 (commit-message). Record `epic_cycle.audit_result: pass` in `state.yaml`.
+3. **Fail (exit 1):** One or more checklist sections fail → **reset `epic_cycle.current_step` to `4`** (develop-tdd) and add the failing section IDs to `completed_steps` as `"1,2,3,4,5,6(fail: ...)"`. Record `epic_cycle.audit_result: fail` in `state.yaml`. Do NOT advance past step 6 until audit passes.
+4. **Audit artifact:** Full audit report saved to `specs/verifications/AUDIT-<epic>-<story>.md` regardless of pass/fail, for reviewer traceability.
+
 ## Handoff
 
 Write `handoff.next_skill` and `handoff.context` in `state.yaml` when pausing mid-epic.

package/.pi/skills/validate-contracts/SKILL.md

@@ -0,0 +1,183 @@
+---
+name: validate-contracts
+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.\""
+model: sonnet
+---
+
+
+# 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:
+
+```
+specs/contracts/
+├── users.schema.yaml        # API response schema
+├── i18n-keys.yaml           # Key-set comparison
+├── migration-output.yaml    # Data shape contract
+└── README.md                # Local conventions
+```
+
+### 1. API Response Contracts (`--schema`)
+
+Define expected API response shapes and validate live endpoints against them:
+
+```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 }
+```
+
+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:
+
+```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
+```
+
+Usage:
+
+```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)
+```
+
+### 3. Data Shape Contracts (`--shape`)
+
+Validate that a data file matches expected column types and constraints:
+
+```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
+```
+
+Usage:
+
+```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)
+```
+
+## 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
+```
+
+## 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`

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+# [2.14.0](https://github.com/danielvm-git/bigpowers/compare/v2.13.0...v2.14.0) (2026-06-21)
+
+
+### Features
+
+* **e18s01:** audit-code as non-optional gate in build-epic step 6 ([48f08de](https://github.com/danielvm-git/bigpowers/commit/48f08de62952827966ace0ac9149cea882fa0ca5))
+
+# [2.13.0](https://github.com/danielvm-git/bigpowers/compare/v2.12.1...v2.13.0) (2026-06-21)
+
+
+### Features
+
+* **skills:** add validate-contracts — data contract validator ([ec32076](https://github.com/danielvm-git/bigpowers/commit/ec3207617b3d465f8e5223242124cd2366cc2103))
+
 ## [2.12.1](https://github.com/danielvm-git/bigpowers/compare/v2.12.0...v2.12.1) (2026-06-20)
 
 

package/SKILL-INDEX.md

@@ -3,8 +3,8 @@
 > **DO NOT EDIT** — This file is auto-generated by `scripts/generate-skill-index.sh`.
 > Edit `SKILL.md` source files or `skills-lock.json` instead. Run `bash scripts/sync-skills.sh` to regenerate.
 
-**Generated:** 2026-06-20T21:59:15Z
-**Skills:** 66
+**Generated:** 2026-06-21T21:27:17Z
+**Skills:** 67
 
 ---
 
@@ -15,11 +15,11 @@
 | Discover | 6 | `elaborate-spec, map-codebase, research-first, search-skills, survey-context, using-bigpowers` |
 | Design | 7 | `deepen-architecture, define-language, define-success, design-interface, grill-me, grill-with-docs, model-domain` |
 | Plan | 9 | `assess-impact, change-request, plan-refactor, plan-release, plan-work, run-planning, scope-work, seed-conventions, slice-tasks` |
-| Build | 16 | `align-grid, build-epic, craft-skill, deploy, develop-tdd, execute-plan, guard-git, hook-commits, kickoff-branch, orchestrate-project, publish-package, setup-environment, smoke-test, spike-prototype, wire-ci, wire-observability` |
+| Build | 17 | `align-grid, build-epic, craft-skill, deploy, develop-tdd, execute-plan, guard-git, hook-commits, kickoff-branch, orchestrate-project, publish-package, setup-environment, smoke-test, spike-prototype, validate-contracts, wire-ci, wire-observability` |
 | Verify | 12 | `audit-code, diagnose-root, enforce-first, fix-bug, inspect-quality, investigate-bug, request-review, respond-review, run-evals, trace-requirement, validate-fix, verify-work` |
 | Release | 2 | `commit-message, release-branch` |
 | Sustain | 13 | `compose-workflow, delegate-task, dispatch-agents, edit-document, evolve-skill, migrate-spec, organize-workspace, reset-baseline, session-state, simulate-agents, stocktake-skills, terse-mode, write-document` |
-| **TOTAL** | **65** | |
+| **TOTAL** | **66** | |
 
 ---
 
@@ -63,37 +63,38 @@
 | 34 | Build | `setup-environment` | Pre-install dependencies and configure tools before development work begins. Use | ✅ Active |
 | 35 | Build | `smoke-test` | "Post-deploy health-check against a live URL. Validates HTTP status, response co | ✅ Active |
 | 36 | Build | `spike-prototype` | Throw-away prototype for unknown problem spaces. Output is learning notes in spe | ✅ Active |
-| 37 | Build | `wire-ci` | "CI pipeline setup with pre-built templates and local validation. Generates GitH | ✅ Active |
-| 38 | Build | `wire-observability` | Add structured JSON logging, observability commands, and idempotent setup script | ✅ Active |
-| 39 | Verify | `audit-code` | Self-review checklist for the coding agent to run before dispatching a reviewer. | ✅ Active |
-| 40 | Verify | `diagnose-root` | Run 4-phase root cause analysis — reproduce, isolate, hypothesize, verify. Use | ✅ Active |
-| 41 | Verify | `enforce-first` | Apply the F.I.R.S.T test quality rubric (Fast, Independent, Repeatable, Self-Val | ✅ Active |
-| 42 | Verify | `fix-bug` | Bug fix orchestrator — active_flow fix_bug; reads specs/bugs/BUG-*.md; chains  | ✅ Active |
-| 43 | Verify | `inspect-quality` | Interactive QA session where user reports bugs or issues conversationally, and t | ✅ Active |
-| 44 | Verify | `investigate-bug` | Investigate a bug or issue by exploring the codebase to find root cause, then wr | ✅ Active |
-| 45 | Verify | `request-review` | Dispatch a fresh reviewer agent with a clean context to critique the code after  | ✅ Active |
-| 46 | Verify | `respond-review` | Act on a reviewer agent's feedback systematically — categorize findings, apply | ✅ Active |
-| 47 | Verify | `run-evals` | Eval-Driven Development — define capability and regression evals before buildi | ✅ Active |
-| 48 | Verify | `trace-requirement` | Link story IDs from specs/release-plan.yaml + epic capsule directories to the im | ✅ Active |
-| 49 | Verify | `validate-fix` | Prove a fix works before declaring done — re-run the failing test, run the ful | ✅ Active |
-| 50 | Verify | `verify-work` | Multi-phase UAT gate — cold-start smoke, build, typecheck, lint, tests, step-b | ✅ Active |
-| 51 | Release | `commit-message` | Reviews working-tree changes, then drafts a Conventional Commits title/body and  | ✅ Active |
-| 52 | Release | `release-branch` | Make the merge/PR/keep/discard decision for a feature branch, verify coverage ga | ✅ Active |
-| 53 | Sustain | `compose-workflow` | Chain multiple bigpowers skills into a custom workflow recipe saved in specs/. U | ✅ Active |
-| 54 | Sustain | `delegate-task` | Delegate one complex task to a single subagent, review its work in two stages be | ✅ Active |
-| 55 | Sustain | `dispatch-agents` | Dispatch multiple subagents in parallel on independent tasks. No waiting between | ✅ Active |
-| 56 | Sustain | `edit-document` | Edit and improve documents by restructuring sections, improving clarity, and tig | ✅ Active |
-| 57 | Sustain | `evolve-skill` | Benchmark-gated skill evolution — consume bigpowers-benchmark report, propose  | ✅ Active |
-| 58 | Sustain | `migrate-spec` | Detect GSD, spec-kit, or BMAD spec artifacts and transform them into bigpowers Y | ✅ Active |
-| 59 | Sustain | `organize-workspace` | Scans the active workspace for disposable artifacts—logs, caches, stale build  | ✅ Active |
-| 60 | Sustain | `reset-baseline` | Restore the project to a known clean state between agent runs or experiments. Us | ✅ Active |
-| 61 | Sustain | `session-state` | Track implementation decisions and progress in specs/state.yaml to prevent conte | ✅ Active |
-| 62 | Sustain | `simulate-agents` | Run Mock User and Auditor agents against a feature in fresh contexts before huma | ✅ Active |
-| 63 | Sustain | `stocktake-skills` | Sequential subagent batch audit of the bigpowers skill catalog — Quick Scan (c | ✅ Active |
-| 64 | Sustain | `terse-mode` | Fallback ultra-compressed communication mode. Cuts token usage ~75% by dropping  | ✅ Active |
-| 65 | Sustain | `write-document` | Write, organize, and sync high-integrity technical documents using the BMAD meth | ✅ Active |
-
-**Total: 65 active skills.**
+| 37 | Build | `validate-contracts` | "Assert data shape consistency across system boundaries — live API responses a | ✅ Active |
+| 38 | Build | `wire-ci` | "CI pipeline setup with pre-built templates and local validation. Generates GitH | ✅ Active |
+| 39 | Build | `wire-observability` | Add structured JSON logging, observability commands, and idempotent setup script | ✅ Active |
+| 40 | Verify | `audit-code` | Self-review checklist for the coding agent to run before dispatching a reviewer. | ✅ Active |
+| 41 | Verify | `diagnose-root` | Run 4-phase root cause analysis — reproduce, isolate, hypothesize, verify. Use | ✅ Active |
+| 42 | Verify | `enforce-first` | Apply the F.I.R.S.T test quality rubric (Fast, Independent, Repeatable, Self-Val | ✅ Active |
+| 43 | Verify | `fix-bug` | Bug fix orchestrator — active_flow fix_bug; reads specs/bugs/BUG-*.md; chains  | ✅ Active |
+| 44 | Verify | `inspect-quality` | Interactive QA session where user reports bugs or issues conversationally, and t | ✅ Active |
+| 45 | Verify | `investigate-bug` | Investigate a bug or issue by exploring the codebase to find root cause, then wr | ✅ Active |
+| 46 | Verify | `request-review` | Dispatch a fresh reviewer agent with a clean context to critique the code after  | ✅ Active |
+| 47 | Verify | `respond-review` | Act on a reviewer agent's feedback systematically — categorize findings, apply | ✅ Active |
+| 48 | Verify | `run-evals` | Eval-Driven Development — define capability and regression evals before buildi | ✅ Active |
+| 49 | Verify | `trace-requirement` | Link story IDs from specs/release-plan.yaml + epic capsule directories to the im | ✅ Active |
+| 50 | Verify | `validate-fix` | Prove a fix works before declaring done — re-run the failing test, run the ful | ✅ Active |
+| 51 | Verify | `verify-work` | Multi-phase UAT gate — cold-start smoke, build, typecheck, lint, tests, step-b | ✅ Active |
+| 52 | Release | `commit-message` | Reviews working-tree changes, then drafts a Conventional Commits title/body and  | ✅ Active |
+| 53 | Release | `release-branch` | Make the merge/PR/keep/discard decision for a feature branch, verify coverage ga | ✅ Active |
+| 54 | Sustain | `compose-workflow` | Chain multiple bigpowers skills into a custom workflow recipe saved in specs/. U | ✅ Active |
+| 55 | Sustain | `delegate-task` | Delegate one complex task to a single subagent, review its work in two stages be | ✅ Active |
+| 56 | Sustain | `dispatch-agents` | Dispatch multiple subagents in parallel on independent tasks. No waiting between | ✅ Active |
+| 57 | Sustain | `edit-document` | Edit and improve documents by restructuring sections, improving clarity, and tig | ✅ Active |
+| 58 | Sustain | `evolve-skill` | Benchmark-gated skill evolution — consume bigpowers-benchmark report, propose  | ✅ Active |
+| 59 | Sustain | `migrate-spec` | Detect GSD, spec-kit, or BMAD spec artifacts and transform them into bigpowers Y | ✅ Active |
+| 60 | Sustain | `organize-workspace` | Scans the active workspace for disposable artifacts—logs, caches, stale build  | ✅ Active |
+| 61 | Sustain | `reset-baseline` | Restore the project to a known clean state between agent runs or experiments. Us | ✅ Active |
+| 62 | Sustain | `session-state` | Track implementation decisions and progress in specs/state.yaml to prevent conte | ✅ Active |
+| 63 | Sustain | `simulate-agents` | Run Mock User and Auditor agents against a feature in fresh contexts before huma | ✅ Active |
+| 64 | Sustain | `stocktake-skills` | Sequential subagent batch audit of the bigpowers skill catalog — Quick Scan (c | ✅ Active |
+| 65 | Sustain | `terse-mode` | Fallback ultra-compressed communication mode. Cuts token usage ~75% by dropping  | ✅ Active |
+| 66 | Sustain | `write-document` | Write, organize, and sync high-integrity technical documents using the BMAD meth | ✅ Active |
+
+**Total: 66 active skills.**
 
 ---
 

package/audit-code/SKILL.md

@@ -16,6 +16,7 @@ Run this self-review before asking anyone else to look at the code. The goal is
 
 - Default: full checklist
 - --quick: Run only Supply Chain and Test Coverage. Use for changes under 50 LOC.
+- --gate: Non-interactive mode for automated CI gating (used by build-epic step 6). Exit with non-zero status code (`exit 1`) on ANY checklist failure; `exit 0` only if ALL items pass. Produces a compact pass/fail summary to stderr. On failure, list every ✗ item with reason.
 
 ## Checklist
 
@@ -105,6 +106,19 @@ Report the checklist with ✓ / ✗ per item. For each ✗, describe what needs
 If all items pass: suggest running `request-review` for an independent second opinion.
 If any items fail: fix them before proceeding.
 
+### Gate mode output (`--gate`)
+
+In `--gate` mode, print one summary line per checklist section:
+
+```
+PASS Supply Chain & Security
+FAIL Provenance & Metadata (2 items)
+PASS Law of Demeter
+...
+```
+
+Aggregate exit code: `0` if all sections PASS, `1` (non-zero) if any section FAILs. Write the full audit report to `specs/verifications/AUDIT-<epic>-<story>.md` as a permanent record.
+
 ## Handoff
 
 Gate: READY -> next: commit-message

package/build-epic/SKILL.md

@@ -23,7 +23,7 @@ Orchestrates the **build** flow for a single epic: survey → plan tasks → kic
 | 3 | `kickoff-branch` — feature branch + clean baseline |
 | 4 | `develop-tdd` — red-green per task |
 | 5 | `verify-work` — UAT + mechanical gates |
-| 6 | `audit-code` — self-review checklist |
+| 6 | `audit-code` — **non-optional gate** (pass/fail; fail → loop back to step 4) |
 | 7 | `commit-message` — Conventional Commits draft |
 | 8 | `release-branch` — PR or solo land |
 
@@ -36,6 +36,15 @@ Orchestrates the **build** flow for a single epic: survey → plan tasks → kic
 5. After step verify passes, increment `epic_cycle.step` in `state.yaml` (or `bash scripts/bp-yaml-set.sh` if available).
 6. On story complete, set `execution-status.yaml` story key to `done`; run `bash scripts/sync-status-from-epics.sh`.
 
+### Step 6 — audit-code gate (non-optional)
+
+After step 5 (verify-work) completes successfully, step 6 runs `audit-code` automatically in `--gate` mode:
+
+1. **Run audit:** Invoke `audit-code --gate` on the complete diff for this story.
+2. **Pass (exit 0):** All checklist sections pass → advance to step 7 (commit-message). Record `epic_cycle.audit_result: pass` in `state.yaml`.
+3. **Fail (exit 1):** One or more checklist sections fail → **reset `epic_cycle.current_step` to `4`** (develop-tdd) and add the failing section IDs to `completed_steps` as `"1,2,3,4,5,6(fail: ...)"`. Record `epic_cycle.audit_result: fail` in `state.yaml`. Do NOT advance past step 6 until audit passes.
+4. **Audit artifact:** Full audit report saved to `specs/verifications/AUDIT-<epic>-<story>.md` regardless of pass/fail, for reviewer traceability.
+
 ## Handoff
 
 Write `handoff.next_skill` and `handoff.context` in `state.yaml` when pausing mid-epic.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bigpowers",
-  "version": "2.12.1",
+  "version": "2.14.0",
   "description": "61 agent skills for spec-driven, test-first software development by solo developers",
   "main": "index.js",
   "scripts": {

package/scripts/generate-skill-index.sh

@@ -58,6 +58,7 @@ PHASE_MAP=(
   [hook-commits]="Build"
   [deploy]="Build"
   [smoke-test]="Build"
+  [validate-contracts]="Build"
   # Verify
   [verify-work]="Verify"
   [validate-fix]="Verify"

package/skills-lock.json

@@ -13,12 +13,12 @@
     },
     "audit-code": {
       "description": "Self-review checklist for the coding agent to run before dispatching a reviewer. Checks CONVENTIONS.md compliance, Boy Scout Rule, test coverage, types, and SOLID. Produces a pass/fail checklist. Use before request-review, before committing, or when user asks for a code quality check.",
-      "sha256": "e9fa22fc69b1b3ab",
+      "sha256": "8192ebe6f66a9f91",
       "path": "audit-code/SKILL.md"
     },
     "build-epic": {
       "description": "Eight-step epic build cycle — reads state.yaml, execution-status.yaml, and one epic capsule; updates status via bp-yaml-set or direct edit. Resume mode runs one step per invocation. Use instead of ad-hoc execute-plan for release work.",
-      "sha256": "6f0639f6d8886e28",
+      "sha256": "ac7c8fc9740c4beb",
       "path": "build-epic/SKILL.md"
     },
     "change-request": {
@@ -301,6 +301,11 @@
       "sha256": "b150ea218b529f61",
       "path": "using-bigpowers/SKILL.md"
     },
+    "validate-contracts": {
+      "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.\"",
+      "sha256": "17653c7ac211c5d8",
+      "path": "validate-contracts/SKILL.md"
+    },
     "validate-fix": {
       "description": "Prove a fix works before declaring done — re-run the failing test, run the full suite, typecheck, lint, and harden against recurrence. Use after implementing a bug fix, when user says \"is this fixed?\", or before closing an investigation.",
       "sha256": "80fc28e511a501dc",

package/validate-contracts/SKILL.md

@@ -0,0 +1,182 @@
+---
+name: validate-contracts
+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."
+model: sonnet
+---
+
+# 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:
+
+```
+specs/contracts/
+├── users.schema.yaml        # API response schema
+├── i18n-keys.yaml           # Key-set comparison
+├── migration-output.yaml    # Data shape contract
+└── README.md                # Local conventions
+```
+
+### 1. API Response Contracts (`--schema`)
+
+Define expected API response shapes and validate live endpoints against them:
+
+```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 }
+```
+
+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:
+
+```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
+```
+
+Usage:
+
+```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)
+```
+
+### 3. Data Shape Contracts (`--shape`)
+
+Validate that a data file matches expected column types and constraints:
+
+```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
+```
+
+Usage:
+
+```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)
+```
+
+## 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
+```
+
+## 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`