bigpowers 2.85.2 → 2.86.1

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

@@ -10,60 +10,30 @@ description: "Assert data shape consistency across system boundaries — live AP
 >
 > **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.
+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 |
+| **Schema** | API response shape mismatches | 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 |
+| **Shape** | Column type or format violations | 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:
+All contract files live in `specs/contracts/` as YAML. See [REFERENCE.md](REFERENCE.md) for extended examples.
 
-See [REFERENCE.md](REFERENCE.md) for examples.
+### Key-set example
 
-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)
+```yaml
+# specs/contracts/i18n-keys.yaml
+sources:
+  reference: src/locales/en.json
+  target: src/messages/en.json
+mode: subset
 ```
 
-### 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
@@ -73,29 +43,20 @@ Create a YAML file in `specs/contracts/` following the schema for the mode.
 ### 2. Run validation
 
 ```bash
-bash scripts/validate-contracts.sh <contract-file>
+bash scripts/validate-contracts.sh specs/contracts/<contract>.yaml
 ```
 
-The runner auto-detects the contract type from the file content (presence of `schema:`,
-`sources:`, or `file:` + `fields:` keys).
+The runner auto-detects key-set contracts (`sources:` block). Schema and shape modes are documented in REFERENCE.md for consumer projects.
 
 ### 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"}
+PASS: key-set contract
+# or
+FAIL: key-set — N keys in reference missing from target
 ```
 
-Final summary:
-
-```
-=== Validate Contracts Summary ===
-Schema: 3/3 pass | Key-set: 1/1 fail | Shape: 2/2 pass
-FAILED: 1 contract has divergence
-```
+JSON Lines output for CI is planned for schema/shape modes; key-set failures exit non-zero.
 
 ### 4. Fix divergence
 
@@ -106,10 +67,17 @@ FAILED: 1 contract has divergence
 ### 5. Re-validate
 
 ```bash
-bash scripts/validate-contracts.sh <contract-file>
-# → All pass → ready to deploy
+bash scripts/validate-contracts.sh specs/contracts/<contract>.yaml
 ```
 
+## Verify arc
+
+Part of **★ VERIFY ★**: `verify-work` → `validate-contracts` → `smoke-test` → `run-evals` → `audit-code`
+
+## Verify
+
+→ 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`
+
 ---
 
 # Validate Contracts — Reference

package/.zcode/skills/validate-fix/SKILL.md

@@ -5,7 +5,7 @@ description: "Prove a fix works before declaring done — re-run the failing tes
 ---
 
 # Validate Fix
-> **HARD GATE** — **HARD GATE** — Fix must not regress. Run full test suite and manual UAT before declaring success. A fix that passes tests but breaks something else is a failure.
+> **HARD GATE** — Fix must not regress. Run full test suite and manual UAT before declaring success.
 
 
 Prove the fix works. "I think it works" is not evidence. Run the suite, show the output, then harden against recurrence.
@@ -63,10 +63,13 @@ For every bug fixed, add at least one prevention layer:
 - [ ] At least one hardening mechanism added
 - [ ] Hardening mechanism is tested
 
-> **Security recurrence hardening** — If the bug's security-impact assessment (from investigate-bug) was MEDIUM or higher, additionally check:
-> - [ ] Security regression test added (covers the exploit path)
-> - [ ] False-positive exclusion rule added (if applicable)
-> - [ ] Threat model updated (if impact was HIGH+)
+### 5b. Generalize-fix (HARD GATE — e80s04 / GH #98)
+
+Sweep the **defect class** across the codebase after local hardening — see [REFERENCE-generalize-fix.md](REFERENCE-generalize-fix.md).
+
+- [ ] Defect class documented (not just the one-line root cause)
+- [ ] Grep sweep run and `match_count` recorded
+- [ ] `verify-generalize-sweep.sh` passes on the artifact
 
 ### 6. Update the bug file and registry.yaml
 
@@ -104,3 +107,41 @@ Mechanical verification (tests passing) is only half the fix. You must prove **b
 - **The verify command from specs/bugs/BUG-*.md or the active epic task `verify` field must pass**
 
 Suggest next skill: `audit-code` → `commit-message`.
+
+## Verify
+
+→ verify: `grep -q 'generalize-fix' skills/validate-fix/SKILL.md && test -x scripts/verify-generalize-sweep.sh && bash scripts/verify-generalize-sweep.sh --self-test && echo OK`
+
+---
+
+# Generalize-fix (e80s04 / GH #98)
+
+After local hardening in `validate-fix`, sweep the **defect class** across the codebase.
+
+## Steps
+
+1. **Classify** — name the pattern (e.g. `unscoped org query`, `fail-open verify`, `hardcoded package manager`).
+2. **Sweep** — grep for sibling instances; record `match_count` and `grep_pattern`.
+3. **Resolve** — patch all matches in this PR **or** file one tracking issue listing every remaining instance.
+4. **Artifact** — write sweep evidence before declaring done:
+
+```bash
+cat > specs/verifications/generalize-sweep-BUG-YYYY-MM-DD-slug.json <<EOF
+{
+  "defect_class": "fail-open-verify",
+  "grep_pattern": "\\\\|\\\\| echo",
+  "match_count": 0,
+  "sweep_scope": "skills/*/SKILL.md",
+  "patched_in_pr": [],
+  "tracked_issues": []
+}
+EOF
+bash scripts/verify-generalize-sweep.sh specs/verifications/generalize-sweep-*.json
+```
+
+## Security classes
+
+When the defect class is security- or gate-relevant:
+
+- Add a row to `security-review` CWE fixture table (see `skills/security-review/SKILL.md` § CWE mapping mandate).
+- If security-impact was MEDIUM+: add regression test, false-positive exclusion rule, and threat-model update (HIGH+).

package/CHANGELOG.md

@@ -1,3 +1,24 @@
+## [2.86.1](https://github.com/danielvm-git/bigpowers/compare/v2.86.0...v2.86.1) (2026-07-26)
+
+
+### Bug Fixes
+
+* **ci:** make skill-verify bash-3.2 safe and gate release on it ([a5fee16](https://github.com/danielvm-git/bigpowers/commit/a5fee16c70b29094bad0bd803a43797c9b4bd7b6)), closes [#96](https://github.com/danielvm-git/bigpowers/issues/96) [#96](https://github.com/danielvm-git/bigpowers/issues/96) [#99](https://github.com/danielvm-git/bigpowers/issues/99)
+* **ci:** restore truncated SKILL-INDEX and exempt comments from bash-4 guard ([c680896](https://github.com/danielvm-git/bigpowers/commit/c680896528732cff131161e2a1524730db15fd13))
+
+# [2.86.0](https://github.com/danielvm-git/bigpowers/compare/v2.85.2...v2.86.0) (2026-07-25)
+
+
+### Bug Fixes
+
+* **e80:** pass skill size caps and specs YAML validation ([48b06c3](https://github.com/danielvm-git/bigpowers/commit/48b06c3e2e450914035d8ee562e17365d55130dd))
+* **verify:** replace placeholder verify directives with CI-safe checks ([80d0c8d](https://github.com/danielvm-git/bigpowers/commit/80d0c8d3f96375c0b1daeead228bf04ce16a5e6a))
+
+
+### Features
+
+* **e80:** verify arc hardening for [#97](https://github.com/danielvm-git/bigpowers/issues/97) and [#98](https://github.com/danielvm-git/bigpowers/issues/98) ([45f05cf](https://github.com/danielvm-git/bigpowers/commit/45f05cfedbf8be42f4967b8804fe12a81e2b53ef))
+
 ## [2.85.2](https://github.com/danielvm-git/bigpowers/compare/v2.85.1...v2.85.2) (2026-07-25)
 
 

package/SKILL-INDEX.md

@@ -14,8 +14,8 @@
 | Discover | 8 | `audit-plan, elaborate-spec, find-way, 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 | 19 | `align-grid, build-epic, craft-skill, deploy, develop-tdd, execute-plan, extract-design, guard-git, hook-commits, kickoff-branch, orchestrate-project, publish-package, quick-fix, setup-environment, smoke-test, spike-prototype, validate-contracts, wire-ci, wire-observability` |
-| Verify | 18 | `audit-code, context7-mcp, diagnose-root, diagnose-stall, enforce-first, fix-bug, gate-trace, generate-allure-report, inspect-quality, investigate-bug, plan-tests, request-review, respond-review, run-evals, security-review, trace-requirement, validate-fix, verify-work` |
+| Build | 17 | `align-grid, build-epic, craft-skill, deploy, develop-tdd, execute-plan, extract-design, guard-git, hook-commits, kickoff-branch, orchestrate-project, publish-package, quick-fix, setup-environment, spike-prototype, wire-ci, wire-observability` |
+| Verify | 20 | `audit-code, context7-mcp, diagnose-root, diagnose-stall, enforce-first, fix-bug, gate-trace, generate-allure-report, inspect-quality, investigate-bug, plan-tests, request-review, respond-review, run-evals, security-review, smoke-test, trace-requirement, validate-contracts, validate-fix, verify-work` |
 | Release | 2 | `commit-message, release-branch` |
 | Sustain | 17 | `compose-workflow, delegate-task, dispatch-agents, edit-document, evolve-skill, harden-vps, maintain-wiki, migrate-spec, organize-workspace, reset-baseline, run-benchmark, session-state, simulate-agents, stocktake-skills, terse-mode, visual-dashboard, write-document` |
 | **TOTAL** | **80** | |
@@ -64,27 +64,27 @@
 | 36 | Build | `publish-package` | "Package registry publishing for npm, crates.io, PyPI, and Homebrew. Verifies pr | ✅ Active |
 | 37 | Build | `quick-fix` | "Streamlined fast-path for trivial data-only fixes — no TDD, no branching cere | ✅ Active |
 | 38 | Build | `setup-environment` | Pre-install dependencies and configure tools before development work begins. Use | ✅ Active |
-| 39 | Build | `smoke-test` | "Post-deploy health-check against a live URL. Validates HTTP status, response co | ✅ Active |
-| 40 | Build | `spike-prototype` | Throw-away prototype for unknown problem spaces. Output is learning notes in spe | ✅ Active |
-| 41 | Build | `validate-contracts` | "Assert data shape consistency across system boundaries — live API responses a | ✅ Active |
-| 42 | Build | `wire-ci` | "CI pipeline setup with pre-built templates and local validation. Generates GitH | ✅ Active |
-| 43 | Build | `wire-observability` | Add structured JSON logging, observability commands, and idempotent setup script | ✅ Active |
-| 44 | Verify | `audit-code` | Self-review checklist for the coding agent to run before dispatching a reviewer. | ✅ Active |
-| 45 | Verify | `context7-mcp` | Fetch current library docs via Context7 MCP instead of training data. Use when u | ✅ Active |
-| 46 | Verify | `diagnose-root` | Run 4-phase root cause analysis — reproduce, isolate, hypothesize, verify. Use | ✅ Active |
-| 47 | Verify | `diagnose-stall` | Diagnose why agent orchestration stopped producing progress — silent stalls in | ✅ Active |
-| 48 | Verify | `enforce-first` | Apply the F.I.R.S.T test quality rubric (per CONVENTIONS.md §Tests) to a test s | ✅ Active |
-| 49 | Verify | `fix-bug` | Bug fix orchestrator — active_flow fix_bug; reads specs/bugs/BUG-*.md; chains  | ✅ Active |
-| 50 | Verify | `gate-trace` | "Deterministic traceability quality gate — reads coverage matrix + blind-spot  | ✅ Active |
-| 51 | Verify | `generate-allure-report` | "Generate Allure-ready reports from bigpowers YAML metadata. Reads execution-sta | ✅ Active |
-| 52 | Verify | `inspect-quality` | Interactive QA session where user reports bugs or issues conversationally, and t | ✅ Active |
-| 53 | Verify | `investigate-bug` | Investigate a bug or issue by exploring the codebase to find root cause, then wr | ✅ Active |
-| 54 | Verify | `plan-tests` | "Design a risk-scaled test architecture for an epic before implementation begins | ✅ Active |
-| 55 | Verify | `request-review` | Dispatch a fresh reviewer agent with a clean context to critique the code after  | ✅ Active |
-| 56 | Verify | `respond-review` | Act on a reviewer agent's feedback systematically — categorize findings, apply | ✅ Active |
-| 57 | Verify | `run-evals` | Eval-Driven Development — define capability and regression evals before buildi | ✅ Active |
-| 58 | Verify | `security-review` | > | ✅ Active |
-| 59 | Verify | `trace-requirement` | Link story IDs from specs/release-plan.yaml + epic capsule directories to the im | ✅ Active |
+| 39 | Build | `spike-prototype` | Throw-away prototype for unknown problem spaces. Output is learning notes in spe | ✅ Active |
+| 40 | Build | `wire-ci` | "CI pipeline setup with pre-built templates and local validation. Generates GitH | ✅ Active |
+| 41 | Build | `wire-observability` | Add structured JSON logging, observability commands, and idempotent setup script | ✅ Active |
+| 42 | Verify | `audit-code` | Self-review checklist for the coding agent to run before dispatching a reviewer. | ✅ Active |
+| 43 | Verify | `context7-mcp` | Fetch current library docs via Context7 MCP instead of training data. Use when u | ✅ Active |
+| 44 | Verify | `diagnose-root` | Run 4-phase root cause analysis — reproduce, isolate, hypothesize, verify. Use | ✅ Active |
+| 45 | Verify | `diagnose-stall` | Diagnose why agent orchestration stopped producing progress — silent stalls in | ✅ Active |
+| 46 | Verify | `enforce-first` | Apply the F.I.R.S.T test quality rubric (per CONVENTIONS.md §Tests) to a test s | ✅ Active |
+| 47 | Verify | `fix-bug` | Bug fix orchestrator — active_flow fix_bug; reads specs/bugs/BUG-*.md; chains  | ✅ Active |
+| 48 | Verify | `gate-trace` | "Deterministic traceability quality gate — reads coverage matrix + blind-spot  | ✅ Active |
+| 49 | Verify | `generate-allure-report` | "Generate Allure-ready reports from bigpowers YAML metadata. Reads execution-sta | ✅ Active |
+| 50 | Verify | `inspect-quality` | Interactive QA session where user reports bugs or issues conversationally, and t | ✅ Active |
+| 51 | Verify | `investigate-bug` | Investigate a bug or issue by exploring the codebase to find root cause, then wr | ✅ Active |
+| 52 | Verify | `plan-tests` | "Design a risk-scaled test architecture for an epic before implementation begins | ✅ Active |
+| 53 | Verify | `request-review` | Dispatch a fresh reviewer agent with a clean context to critique the code after  | ✅ Active |
+| 54 | Verify | `respond-review` | Act on a reviewer agent's feedback systematically — categorize findings, apply | ✅ Active |
+| 55 | Verify | `run-evals` | Eval-Driven Development — define capability and regression evals before buildi | ✅ Active |
+| 56 | Verify | `security-review` | > | ✅ Active |
+| 57 | Verify | `smoke-test` | "Post-deploy health-check against a live URL. Validates HTTP status, response co | ✅ Active |
+| 58 | Verify | `trace-requirement` | Link story IDs from specs/release-plan.yaml + epic capsule directories to the im | ✅ Active |
+| 59 | Verify | `validate-contracts` | "Assert data shape consistency across system boundaries — live API responses a | ✅ Active |
 | 60 | Verify | `validate-fix` | Prove a fix works before declaring done — re-run the failing test, run the ful | ✅ Active |
 | 61 | Verify | `verify-work` | Multi-phase UAT gate — cold-start smoke, build, typecheck, lint, tests, step-b | ✅ Active |
 | 62 | Release | `commit-message` | Reviews working-tree changes, then drafts a Conventional Commits title/body and  | ✅ Active |
@@ -132,7 +132,7 @@ survey-context → research-first → elaborate-spec → map-codebase
   develop-tdd (+ enforce-first) ←→ delegate-task / dispatch-agents
   execute-plan / build-epic / craft-skill / align-grid
                          ↓
-              ★ VERIFY ★  verify-work → run-evals → audit-code
+              ★ VERIFY ★  verify-work → validate-contracts → smoke-test → run-evals → audit-code
                          ↓
     fix-bug → investigate-bug → diagnose-root → validate-fix
                          ↓

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bigpowers",
-  "version": "2.85.2",
+  "version": "2.86.1",
   "description": "73 agent skills synthesizing 17 years of software engineering discipline into a prescriptive methodology for solo developers",
   "main": "index.js",
   "scripts": {

package/scripts/generate-skill-index.sh

@@ -139,7 +139,7 @@ DESC_COL_WIDTH=56
   echo '  develop-tdd (+ enforce-first) ←→ delegate-task / dispatch-agents'
   echo '  execute-plan / build-epic / craft-skill / align-grid'
   echo '                         ↓'
-  echo '              ★ VERIFY ★  verify-work → run-evals → audit-code'
+  echo '              ★ VERIFY ★  verify-work → validate-contracts → smoke-test → run-evals → audit-code'
   echo '                         ↓'
   echo '    fix-bug → investigate-bug → diagnose-root → validate-fix'
   echo '                         ↓'

package/scripts/run-gate-trace-verify.sh

@@ -0,0 +1,35 @@
+#!/usr/bin/env bash
+# story: e80s01
+# Pre-flight runner for gate-trace skill verify — ensures critic inputs exist.
+# Usage: bash scripts/run-gate-trace-verify.sh [--self-test]
+set -euo pipefail
+
+REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+cd "$REPO_ROOT"
+
+self_test() {
+  local tmp="$REPO_ROOT/specs/verifications/fixtures/gate-trace-selftest"
+  mkdir -p "$tmp"
+  echo '{"stories":{},"coverage_pct":85,"oracle_stats":{"heuristic_ratio":0.2}}' > "$tmp/traceability-matrix.json"
+  echo '{"gaps":[]}' > "$tmp/blind-spots.json"
+  test -f scripts/lib/completeness-critic.sh
+  grep -q 'R1' skills/gate-trace/SKILL.md
+  grep -q 'completeness-critic' skills/gate-trace/SKILL.md
+  echo "run-gate-trace-verify: self-test OK"
+}
+
+if [[ "${1:-}" == "--self-test" ]]; then
+  self_test
+  exit 0
+fi
+
+[[ -f specs/traceability-matrix.json ]] || bash scripts/trace-stories.sh --json
+[[ -f specs/blind-spots.json ]] || bash scripts/check-blind-spots.sh 2>/dev/null || true
+
+if [[ ! -f specs/traceability-matrix.json ]]; then
+  echo "FAIL: missing specs/traceability-matrix.json"
+  exit 1
+fi
+
+bash scripts/lib/completeness-critic.sh
+echo "run-gate-trace-verify: OK"

package/scripts/run-skill-verify.sh

@@ -25,9 +25,46 @@ SKILLS_ROOT="$REPO_ROOT"
 PASS=0; FAIL=0; SKIP=0
 TARGET="${1:-}"
 
+# A directive is fail-open when it cannot exit non-zero on a broken repo.
+# Two families, both checked syntactically because a pipeline's exit status
+# is the status of its LAST command:
+#   1. explicit swallow  — `|| echo ...`, `|| true`, `|| :`, `; true`, `; exit 0`
+#   2. non-asserting tail — pipeline ends in a filter that always exits 0
+#      (head/wc/cat/tee/sort/tr/sed/awk/echo/true/:). `grep x | wc -l` is the
+#      canonical offender: wc always succeeds, so the grep result is discarded.
+# Use an assertion instead, e.g. [ "$(... | wc -l)" -gt 0 ].
+FAIL_OPEN_TAIL_CMDS='head|wc|cat|tee|sort|tr|sed|awk|echo|true|:'
+
 is_fail_open_directive() {
   local cmd="$1"
-  echo "$cmd" | grep -qE '\|\|[[:space:]]*echo|\|[[:space:]]*awk'
+
+  # Family 1: explicit exit-status swallowing.
+  if echo "$cmd" | grep -qE '\|\|[[:space:]]*(echo|true|:)|;[[:space:]]*(true|:|exit[[:space:]]+0)[[:space:]]*$'; then
+    return 0
+  fi
+
+  # Family 2: pipeline whose last stage never fails.
+  # Strip $(...) first — a pipe inside a command substitution feeds an
+  # assertion, e.g. [ "$(ls x | wc -l)" -gt 0 ], and is NOT fail-open.
+  local stripped="$cmd" prev=""
+  while [ "$stripped" != "$prev" ]; do
+    prev="$stripped"
+    stripped=$(printf '%s' "$stripped" | sed 's/\$([^()]*)/SUBST/g')
+  done
+
+  # Only inspect the segment after the final `|` that is not part of `||`.
+  local tail_seg
+  tail_seg=$(printf '%s' "$stripped" | sed 's/||/\
+/g' | tail -1)
+  case "$tail_seg" in
+    *\|*)
+      tail_seg=${tail_seg##*|}
+      tail_seg=$(printf '%s' "$tail_seg" | sed 's/^[[:space:]]*//')
+      echo "$tail_seg" | grep -qE "^($FAIL_OPEN_TAIL_CMDS)([[:space:]]|$)" && return 0
+      ;;
+  esac
+
+  return 1
 }
 
 normalize_verify_cmd() {
@@ -48,7 +85,7 @@ run_verify_cmd() {
   local label="${3:-$skill}"
 
   if is_fail_open_directive "$cmd"; then
-    echo "FAIL: $label — fail-open pattern (|| echo or | awk): $cmd"
+    echo "FAIL: $label — fail-open directive (cannot exit non-zero; swallowed status or non-asserting pipeline tail): $cmd"
     FAIL=$((FAIL + 1))
     return 1
   fi
@@ -71,7 +108,13 @@ run_skill() {
   local skill
   skill=$(dirname "$skill_md")
 
-  mapfile -t verify_lines < <(grep -E '^(> )?→ verify:' "$skill_md" 2>/dev/null || true)
+  # bash 3.2 (macOS default shell) has no `mapfile`. Read the lines portably —
+  # regression guard for the class of BUG-2026-07-02T103911 (`declare -A`).
+  local verify_lines=()
+  local _line
+  while IFS= read -r _line; do
+    [ -n "$_line" ] && verify_lines+=("$_line")
+  done < <(grep -E '^(> )?→ verify:' "$skill_md" 2>/dev/null || true)
 
   if [ "${#verify_lines[@]}" -eq 0 ]; then
     echo "SKIP: $skill"
@@ -112,13 +155,47 @@ run_negative_fixture_self_test() {
     FAIL=$((FAIL + 1))
     return 1
   fi
-  local fail_open_cmd='test -f /nonexistent/path/for/skill-verify-self-test && echo OK || echo FAIL'
-  if ! is_fail_open_directive "$fail_open_cmd"; then
-    echo "FAIL: self-test — fail-open detector did not match canonical || echo pattern"
-    FAIL=$((FAIL + 1))
-    return 1
-  fi
-  echo "PASS: self-test — fail-open detector rejects || echo pattern"
+  # Every known fail-open idiom must be rejected. Add a row here whenever a new
+  # evasion is found — this is the anti-vacuity proof for the detector itself.
+  local bad_patterns='test -f /nope && echo OK || echo FAIL
+test -f /nope || true
+test -f /nope || :
+test -f /nope; true
+test -f /nope; exit 0
+grep -rn "x" . | wc -l
+ls specs/*.md 2>/dev/null | head -15
+git diff --name-only HEAD | head -20
+find . -name "*.md" | cat
+grep x file | awk "{print}"'
+  local bad_line
+  while IFS= read -r bad_line; do
+    [ -z "$bad_line" ] && continue
+    if ! is_fail_open_directive "$bad_line"; then
+      echo "FAIL: self-test — detector missed fail-open idiom: $bad_line"
+      FAIL=$((FAIL + 1))
+      return 1
+    fi
+  done <<EOF
+$bad_patterns
+EOF
+  echo "PASS: self-test — detector rejects all $(printf '%s\n' "$bad_patterns" | grep -c .) known fail-open idioms"
+
+  # And must NOT reject genuine assertions that merely contain a pipe inside $().
+  local good_patterns='[ "$(ls specs/*.yaml 2>/dev/null | wc -l | tr -d " ")" -gt 0 ]
+test -d specs && test -f specs/state.yaml
+[ "$(find specs -name "*.yaml" | wc -l | tr -d " ")" -ge 1 ]'
+  local good_line
+  while IFS= read -r good_line; do
+    [ -z "$good_line" ] && continue
+    if is_fail_open_directive "$good_line"; then
+      echo "FAIL: self-test — detector false-positived on a real assertion: $good_line"
+      FAIL=$((FAIL + 1))
+      return 1
+    fi
+  done <<EOF
+$good_patterns
+EOF
+  echo "PASS: self-test — detector accepts genuine assertions with \$() pipes"
   local real_fail_cmd='test -f /nonexistent/path/for/skill-verify-self-test'
   local output
   if output=$(run_with_timeout "$real_fail_cmd"); then
@@ -157,4 +234,14 @@ fi
 
 echo ""
 echo "Results: $PASS PASS, $FAIL FAIL, $SKIP SKIP"
+
+# SKIP ratchet: skills with no (or non-executable) → verify: are invisible to
+# this gate. Cap the count so the blind spot can only shrink. Lower the ceiling
+# as skills gain real directives; see issue #97.
+SKIP_CEILING="${SKILL_VERIFY_SKIP_CEILING:-34}"
+if [ -z "$TARGET" ] && [ "$SKIP" -gt "$SKIP_CEILING" ]; then
+  echo "FAIL: SKIP count $SKIP exceeds ceiling $SKIP_CEILING — new skills must ship a → verify: directive"
+  FAIL=$((FAIL + 1))
+fi
+
 [ "$FAIL" -eq 0 ]

package/scripts/validate-contracts.sh

@@ -0,0 +1,58 @@
+#!/usr/bin/env bash
+# story: e80s02
+# Contract validation runner for validate-contracts skill.
+# Supports key-set mode (sources.reference vs sources.target JSON key comparison).
+# Usage: bash scripts/validate-contracts.sh <contract.yaml> [--self-test]
+set -euo pipefail
+
+REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+cd "$REPO_ROOT"
+
+self_test() {
+  local dir="$REPO_ROOT/specs/verifications/fixtures/contracts-selftest"
+  mkdir -p "$dir"
+  echo '{"a":1,"b":2,"c":3}' > "$dir/ref.json"
+  echo '{"a":1,"b":2}' > "$dir/target.json"
+  cat > "$dir/keyset.yaml" <<YAML
+sources:
+  reference: specs/verifications/fixtures/contracts-selftest/ref.json
+  target: specs/verifications/fixtures/contracts-selftest/target.json
+mode: subset
+YAML
+  if bash "$0" "$dir/keyset.yaml"; then
+    echo "FAIL: expected divergence on missing key c"
+    exit 1
+  fi
+  echo '{"a":1,"b":2,"c":3}' > "$dir/target.json"
+  bash "$0" "$dir/keyset.yaml"
+  echo "validate-contracts: self-test OK"
+}
+
+if [[ "${1:-}" == "--self-test" ]]; then
+  self_test
+  exit 0
+fi
+
+CONTRACT="${1:-}"
+if [[ -z "$CONTRACT" || ! -f "$CONTRACT" ]]; then
+  echo "Usage: bash scripts/validate-contracts.sh <contract.yaml>"
+  exit 2
+fi
+
+if grep -q '^sources:' "$CONTRACT"; then
+  REF=$(grep 'reference:' "$CONTRACT" | head -1 | awk '{print $2}')
+  TGT=$(grep 'target:' "$CONTRACT" | head -1 | awk '{print $2}')
+  [[ -f "$REF" && -f "$TGT" ]] || { echo "FAIL: missing source files"; exit 1; }
+  REF_KEYS=$(python3 -c "import json; print('\n'.join(sorted(json.load(open('$REF')).keys())))")
+  TGT_KEYS=$(python3 -c "import json; print('\n'.join(sorted(json.load(open('$TGT')).keys())))")
+  MISSING=$(comm -23 <(echo "$REF_KEYS") <(echo "$TGT_KEYS") | wc -l | tr -d ' ')
+  if [[ "$MISSING" -gt 0 ]]; then
+    echo "FAIL: key-set — $MISSING keys in reference missing from target"
+    exit 1
+  fi
+  echo "PASS: key-set contract"
+  exit 0
+fi
+
+echo "SKIP: unsupported contract type in $CONTRACT"
+exit 0

package/scripts/verify-generalize-sweep.sh

@@ -0,0 +1,55 @@
+#!/usr/bin/env bash
+# story: e80s04
+# Validates generalize-fix sweep artifact exists and has required fields.
+# Usage:
+#   bash scripts/verify-generalize-sweep.sh [--self-test]
+#   bash scripts/verify-generalize-sweep.sh specs/verifications/generalize-sweep-BUG-*.json
+set -euo pipefail
+
+REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+cd "$REPO_ROOT"
+
+validate_artifact() {
+  local file="$1"
+  [[ -f "$file" ]] || { echo "FAIL: missing $file"; return 1; }
+  grep -q '"defect_class"' "$file" || { echo "FAIL: $file missing defect_class"; return 1; }
+  grep -q '"grep_pattern"' "$file" || { echo "FAIL: $file missing grep_pattern"; return 1; }
+  grep -q '"match_count"' "$file" || { echo "FAIL: $file missing match_count"; return 1; }
+  echo "PASS: $file"
+}
+
+self_test() {
+  local dir="$REPO_ROOT/specs/verifications/fixtures"
+  mkdir -p "$dir"
+  local sample="$dir/generalize-sweep-selftest.json"
+  cat > "$sample" <<'JSON'
+{
+  "defect_class": "fail-open-verify",
+  "grep_pattern": "|| echo",
+  "match_count": 0,
+  "sweep_scope": "skills/*/SKILL.md",
+  "notes": "self-test fixture for verify-generalize-sweep.sh"
+}
+JSON
+  validate_artifact "$sample"
+  grep -q 'generalize-fix' skills/validate-fix/SKILL.md
+  echo "verify-generalize-sweep: self-test OK"
+}
+
+if [[ "${1:-}" == "--self-test" ]]; then
+  self_test
+  exit 0
+fi
+
+if [[ $# -gt 0 ]]; then
+  for f in "$@"; do validate_artifact "$f"; done
+  exit 0
+fi
+
+shopt -s nullglob
+artifacts=(specs/verifications/generalize-sweep-*.json)
+if [[ ${#artifacts[@]} -eq 0 ]]; then
+  echo "FAIL: no specs/verifications/generalize-sweep-*.json artifact (generalize-fix not evidenced)"
+  exit 1
+fi
+for f in "${artifacts[@]}"; do validate_artifact "$f"; done