bigpowers 2.58.1 → 2.58.2

package/.pi/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bigpowers",
-  "version": "2.58.1",
+  "version": "2.58.2",
   "description": "73 skills — 72 agent skills synthesizing 17 years of software engineering discipline into a prescriptive methodology for solo developers",
   "keywords": [
     "pi-package"

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+## [2.58.2](https://github.com/danielvm-git/bigpowers/compare/v2.58.1...v2.58.2) (2026-07-03)
+
+
+### Bug Fixes
+
+* **gates:** restore lost gap-closure fixes — e13s02 tag, validate-okf.sh, waivers, version ([3ddc000](https://github.com/danielvm-git/bigpowers/commit/3ddc0003288f65a5a7c3f681588d6281a6f83a05))
+
 ## [2.58.1](https://github.com/danielvm-git/bigpowers/compare/v2.58.0...v2.58.1) (2026-07-03)
 
 

package/CONVENTIONS.md

@@ -231,3 +231,15 @@ name must return < 5 results across the repo.
 | `grill-with-docs` | three-word verb-prep-noun | Variant of `grill-me`; the `-with-docs` suffix is the distinguishing feature — collapsing it would hide the doc-grounded contract |
 
 Any new exception requires an entry in this table before the skill is published.
+
+## File-Size Exceptions
+
+The 300-line file cap exists to ensure files fit in a single agent context
+window. The following files are documented exceptions:
+
+| File | Lines | Rationale | Review date |
+|------|-------|-----------|-------------|
+| `scripts/trace-stories.sh` | 613 | Parse-match-report phases are tightly coupled; splitting introduces grep-fragile inter-script state and breaks `set -e` error propagation. Tracked as P3 technical debt (BUG-2026-07-03-trace-stories-613-line). | 2026-10-01 |
+| `scripts/audit-compliance.sh` | ~280 | Gherkin harness with embedded judge logic and waiver subsystem; splitting the judge loop from the reporting layer would require fragile state-passing. Approaching the 300-line cap; monitor. | 2026-10-01 |
+
+Any new exception requires an entry in this table with rationale and a review date.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bigpowers",
-  "version": "2.58.1",
+  "version": "2.58.2",
   "description": "72 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

@@ -1,4 +1,5 @@
 #!/usr/bin/env bash
+# story: e13s02
 # generate-skill-index.sh — Auto-generate SKILL-INDEX.md from skills-lock.json + SKILL.md frontmatter
 # This file is called by sync-skills.sh. Output is SKILL-INDEX.md at repo root.
 # DO NOT edit SKILL-INDEX.md manually — it is auto-generated.

package/scripts/validate-okf.sh

@@ -1,27 +1,35 @@
 #!/usr/bin/env bash
+# story: e38s09
 #
-# validate-okf.sh — provenance gate for OKF story-metrics bundles (e40/e31 style).
+# validate-okf.sh — provenance gate for OKF bundles (e40/e31/e44 style).
 #
-# A bundle is valid iff:
+# Kind-aware: validates story-metrics, spec-migration, and migration-registry
+# bundles against their respective schemas. Fail-closed: unknown flags exit 2,
+# missing directories exit 1. Multi-dir default scans specs/metrics/ AND
+# specs/migrations/.
+#
+# A story-metrics bundle is valid iff:
 #   1. The generator ran (generator field matches scripts/record-cycle-time.sh).
 #   2. commit_range resolves to real commits in the repo.
 #   3. Source enum is valid (measured|estimated|backfilled).
-#   4. Required keys are present with correct aggregation tags.
+#   4. Required keys are present with non-null values.
+#
+# A spec-migration bundle is valid iff:
+#   1. id, title, since_version, order, actions_needed are present.
+#   2. fingerprint.any has at least one file/exists check.
+#
+# A migration-registry bundle is valid iff:
+#   1. migrations list has at least one entry with id + file + status.
 #
 # This script gates on PROVENANCE, NEVER on a specific metric value.
-# Gate on freshness (did the right generator run?) not on outcomes.
 #
 # Usage:
-#   scripts/validate-okf.sh [--dir <path>] [--help]
-#   scripts/validate-okf.sh --bundle <file>      # validate a single bundle
+#   scripts/validate-okf.sh [--dir <path>] [--bundle <file>] [--help]
 #
 set -euo pipefail
 
 ROOT="$(git rev-parse --show-toplevel 2>/dev/null)" || { echo "validate-okf: not inside a git repo"; exit 1; }
-METRICS_DIR="$ROOT/specs/metrics"
 EXIT_CODE=0
-REQUIRED_KEYS="id epic bcps commit_range source generated_at generator"
-VALID_SOURCES="measured estimated backfilled"
 
 RED='\033[0;31m'; GREEN='\033[0;32m'; YELLOW='\033[0;33m'; NC='\033[0m'
 
@@ -30,30 +38,36 @@ usage() {
 Usage: scripts/validate-okf.sh [flags]
 
 Flags:
-  --dir <path>       Validate all OKF bundles in directory (default: specs/metrics/)
+  --dir <path>       Validate all OKF bundles in directory
   --bundle <file>    Validate a single OKF bundle
   --help             Show this message
 
 Description:
-  Provenance gate for OKF story-metrics bundles. Validates that:
-  - Required keys are present (id, epic, bcps, commit_range, source, generated_at, generator)
-  - Source enum is valid (measured|estimated|backfilled)
-  - Generator matches scripts/record-cycle-time.sh
-  - commit_range resolves to real commits
-  - Aggregation tags are present (Σ, ⌀, %, •)
-
-  NEVER gates on a specific metric value — only on provenance and freshness.
+  Kind-aware provenance gate for OKF bundles. Without flags, validates all
+  bundles in specs/metrics/ AND specs/migrations/. NEVER gates on a specific
+  metric value — only on provenance and schema conformance.
+
+  OKF kinds validated:
+    story-metrics       — effort/lead-time provenance (e40)
+    spec-migration      — migration bundle schema (e44)
+    migration-registry  — registry index integrity (e44)
 EOF
   exit 0
 }
 
-# Parse a single YAML frontmatter block from an OKF bundle .md file.
-# Returns the frontmatter as JSON via Python (which handles YAML safely).
+# ---- YAML frontmatter parser (datetime-safe) ---------------------------
 parse_frontmatter() {
   local file="$1"
-  # Extract YAML frontmatter between --- markers
   python3 -c "
-import yaml, sys
+import yaml, sys, json
+
+class SafeEncoder(json.JSONEncoder):
+    def default(self, obj):
+        try:
+            return super().default(obj)
+        except TypeError:
+            return str(obj)
+
 content = open('$file').read()
 parts = content.split('---')
 if len(parts) < 3:
@@ -62,137 +76,226 @@ try:
     fm = yaml.safe_load(parts[1])
     if fm is None:
         sys.exit(1)
-    # Emit as JSON for bash
-    import json
-    print(json.dumps(fm))
+    print(json.dumps(fm, cls=SafeEncoder))
 except Exception as e:
-    print(f'validate-okf: YAML parse error in $file: {e}', file=sys.stderr)
+    print(f'YAML parse error: {e}', file=sys.stderr)
     sys.exit(1)
 " 2>/dev/null
 }
 
-validate_bundle() {
-  local file="$1"
-  local bundle_name; bundle_name="$(basename "$file")"
-
-  # Parse frontmatter
-  local fm
-  fm="$(parse_frontmatter "$file")" || {
-    printf "${RED}FAIL${NC} %s: cannot parse YAML frontmatter\n" "$bundle_name"
-    EXIT_CODE=1
-    return
-  }
+# ---- Kind-specific validators ------------------------------------------
 
-  # Check okf_kind
-  local kind
-  kind="$(echo "$fm" | python3 -c "import json,sys; d=json.load(sys.stdin); print(d.get('okf_kind',''))" 2>/dev/null)"
-  if [ "$kind" != "story-metrics" ]; then
-    printf "${YELLOW}SKIP${NC} %s: not a story-metrics bundle (kind=%s)\n" "$bundle_name" "${kind:-none}"
-    return
-  fi
+validate_story_metrics() {
+  local file="$1" fm="$2" name="$3"
+  local errs=0
 
-  # Check required keys
-  for key in $REQUIRED_KEYS; do
+  # Required keys
+  for key in id epic bcps commit_range source generated_at generator; do
     local val
     val="$(echo "$fm" | python3 -c "import json,sys; d=json.load(sys.stdin); print(d.get('$key',''))" 2>/dev/null)"
     if [ -z "$val" ] || [ "$val" = "null" ] || [ "$val" = "None" ]; then
-      printf "${RED}FAIL${NC} %s: missing required key '%s'\n" "$bundle_name" "$key"
-      EXIT_CODE=1
-      return
+      printf "${RED}FAIL${NC} %s: missing required key '%s'\n" "$name" "$key"
+      errs=$((errs + 1))
     fi
   done
+  [ "$errs" -gt 0 ] && { EXIT_CODE=1; return; }
 
-  # Check source enum
+  # Source enum
   local source
-  source="$(echo "$fm" | python3 -c "import json,sys; d=json.load(sys.stdin); print(d['source'])" 2>/dev/null)"
-  if ! echo "$VALID_SOURCES" | grep -qw "$source"; then
-    printf "${RED}FAIL${NC} %s: invalid source '%s' — must be one of: %s\n" "$bundle_name" "$source" "$VALID_SOURCES"
-    EXIT_CODE=1
-    return
+  source="$(echo "$fm" | python3 -c "import json,sys; d=json.load(sys.stdin); print(d.get('source',''))" 2>/dev/null)"
+  if ! echo "measured estimated backfilled" | grep -qw "$source"; then
+    printf "${RED}FAIL${NC} %s: invalid source '%s' — must be measured|estimated|backfilled\n" "$name" "$source"
+    EXIT_CODE=1; return
   fi
 
-  # Check generator
+  # Generator
   local generator
-  generator="$(echo "$fm" | python3 -c "import json,sys; d=json.load(sys.stdin); print(d['generator'])" 2>/dev/null)"
+  generator="$(echo "$fm" | python3 -c "import json,sys; d=json.load(sys.stdin); print(d.get('generator',''))" 2>/dev/null)"
   if [ "$generator" != "scripts/record-cycle-time.sh" ]; then
-    printf "${RED}FAIL${NC} %s: wrong generator '%s' — expected scripts/record-cycle-time.sh\n" "$bundle_name" "$generator"
-    EXIT_CODE=1
-    return
+    printf "${RED}FAIL${NC} %s: wrong generator '%s' — expected scripts/record-cycle-time.sh\n" "$name" "$generator"
+    EXIT_CODE=1; return
   fi
 
-  # Check commit_range resolves
+  # commit_range resolves
   local commit_range
-  commit_range="$(echo "$fm" | python3 -c "import json,sys; d=json.load(sys.stdin); print(d['commit_range'])" 2>/dev/null)"
+  commit_range="$(echo "$fm" | python3 -c "import json,sys; d=json.load(sys.stdin); print(d.get('commit_range',''))" 2>/dev/null)"
   if ! git -C "$ROOT" log --oneline -1 "$commit_range" >/dev/null 2>&1; then
-    printf "${RED}FAIL${NC} %s: commit_range '%s' does not resolve\n" "$bundle_name" "$commit_range"
-    EXIT_CODE=1
-    return
+    printf "${RED}FAIL${NC} %s: commit_range '%s' does not resolve\n" "$name" "$commit_range"
+    EXIT_CODE=1; return
   fi
 
-  # Check aggregation tags exist (not empty, but don't validate correctness)
-  local effort_hours
-  effort_hours="$(echo "$fm" | python3 -c "import json,sys; d=json.load(sys.stdin); e=d.get('effort',{}); print(e.get('effort_hours',''))" 2>/dev/null)"
-  if [ -z "$effort_hours" ] || [ "$effort_hours" = "null" ]; then
-    printf "${RED}FAIL${NC} %s: effort.effort_hours missing or null\n" "$bundle_name"
-    EXIT_CODE=1
-    return
+  # effort.effort_hours present and non-negative
+  local eff
+  eff="$(echo "$fm" | python3 -c "
+import json,sys
+d=json.load(sys.stdin)
+e=d.get('effort',{}).get('effort_hours')
+if e is None: sys.exit(1)
+if e < 0: sys.exit(2)
+print(e)
+" 2>/dev/null)" || {
+    local rc=$?
+    if [ "$rc" -eq 1 ]; then
+      printf "${RED}FAIL${NC} %s: effort.effort_hours missing or null\n" "$name"
+    else
+      printf "${RED}FAIL${NC} %s: effort_hours out of bounds\n" "$name"
+    fi
+    EXIT_CODE=1; return
+  }
+
+  printf "${GREEN}PASS${NC} %s (source=%s, generator=%s, commit_range resolves)\n" "$name" "$source" "$generator"
+}
+
+validate_spec_migration() {
+  local file="$1" fm="$2" name="$3"
+  local errs=0
+
+  # Required keys
+  for key in id title since_version order actions_needed; do
+    local val
+    val="$(echo "$fm" | python3 -c "import json,sys; d=json.load(sys.stdin); print(d.get('$key',''))" 2>/dev/null)"
+    if [ -z "$val" ] || [ "$val" = "null" ] || [ "$val" = "None" ] || [ "$val" = "[]" ]; then
+      printf "${RED}FAIL${NC} %s: missing required key '%s'\n" "$name" "$key"
+      errs=$((errs + 1))
+    fi
+  done
+  [ "$errs" -gt 0 ] && { EXIT_CODE=1; return; }
+
+  # fingerprint.any has at least one check
+  local fp_count
+  fp_count="$(echo "$fm" | python3 -c "
+import json,sys
+d=json.load(sys.stdin)
+fp=d.get('fingerprint',{}).get('any',[])
+print(len(fp))
+" 2>/dev/null)"
+  if [ "${fp_count:-0}" -eq 0 ]; then
+    printf "${RED}FAIL${NC} %s: fingerprint.any is empty — no detection criteria\n" "$name"
+    EXIT_CODE=1; return
   fi
 
-  # Bounds sanity (effort can't be negative)
-  python3 -c "
-import json, sys
-d = json.load(sys.stdin)
-eff = d.get('effort', {}).get('effort_hours')
-if eff is not None and eff < 0:
-    sys.exit(1)
-" <<< "$fm" 2>/dev/null || {
-    printf "${RED}FAIL${NC} %s: effort_hours out of bounds\n" "$bundle_name"
+  printf "${GREEN}PASS${NC} %s (actions=%s, fingerprint has %s check(s))\n" \
+    "$name" \
+    "$(echo "$fm" | python3 -c "import json,sys; d=json.load(sys.stdin); print(len(d.get('actions_needed',[])))" 2>/dev/null)" \
+    "$fp_count"
+}
+
+validate_migration_registry() {
+  local file="$1" fm="$2" name="$3"
+
+  local count
+  count="$(echo "$fm" | python3 -c "
+import json,sys
+d=json.load(sys.stdin)
+migrations=d.get('migrations',[])
+print(len(migrations))
+" 2>/dev/null)"
+  if [ "${count:-0}" -eq 0 ]; then
+    printf "${RED}FAIL${NC} %s: migrations list is empty\n" "$name"
+    EXIT_CODE=1; return
+  fi
+
+  # Check each migration has id + file + status
+  local bad
+  bad="$(echo "$fm" | python3 -c "
+import json,sys
+d=json.load(sys.stdin)
+for m in d.get('migrations',[]):
+    if not all(k in m for k in ('id','file','status')):
+        print(m.get('id','?')); sys.exit(1)
+" 2>/dev/null)" || {
+    printf "${RED}FAIL${NC} %s: migration '%s' missing id/file/status\n" "$name" "${bad:-?}"
+    EXIT_CODE=1; return
+  }
+
+  printf "${GREEN}PASS${NC} %s (%s migrations indexed)\n" "$name" "$count"
+}
+
+# ---- Main validation dispatcher ----------------------------------------
+validate_bundle() {
+  local file="$1"
+  local name; name="$(basename "$file")"
+
+  local fm
+  fm="$(parse_frontmatter "$file")" || {
+    printf "${RED}FAIL${NC} %s: cannot parse YAML frontmatter\n" "$name"
     EXIT_CODE=1
     return
   }
 
-  printf "${GREEN}PASS${NC} %s (source=%s, generator=%s, commit_range resolves)\n" "$bundle_name" "$source" "$generator"
+  local kind
+  kind="$(echo "$fm" | python3 -c "import json,sys; d=json.load(sys.stdin); print(d.get('okf_kind',''))" 2>/dev/null)"
+
+  case "$kind" in
+    story-metrics)       validate_story_metrics "$file" "$fm" "$name" ;;
+    spec-migration)      validate_spec_migration "$file" "$fm" "$name" ;;
+    migration-registry)  validate_migration_registry "$file" "$fm" "$name" ;;
+    "")
+      printf "${YELLOW}SKIP${NC} %s: no okf_kind — not an OKF bundle\n" "$name"
+      ;;
+    *)
+      printf "${YELLOW}SKIP${NC} %s: unknown okf_kind '%s'\n" "$name" "$kind"
+      ;;
+  esac
+}
+
+# ---- Scan directory ----------------------------------------------------
+scan_dir() {
+  local dir="$1"
+  if [ ! -d "$dir" ]; then
+    printf "${RED}FAIL${NC} directory not found: %s\n" "$dir"
+    EXIT_CODE=1
+    return
+  fi
+  local count=0
+  while IFS= read -r -d '' f; do
+    if head -1 "$f" 2>/dev/null | grep -q '^---$'; then
+      validate_bundle "$f"
+      count=$((count + 1))
+    fi
+  done < <(find "$dir" -maxdepth 1 -name '*.md' -print0 2>/dev/null || true)
+  if [ "$count" -eq 0 ]; then
+    printf "${YELLOW}SKIP${NC} no OKF bundles found in %s\n" "$dir"
+  fi
 }
 
 # ---- main ----------------------------------------------------------------
-DIR=""
+DIRS=()
 BUNDLE=""
+DEFAULT_DIRS=("$ROOT/specs/metrics" "$ROOT/specs/migrations")
 
-[ $# -ge 1 ] || set -- "--dir" "$METRICS_DIR"  # default: validate specs/metrics/
+if [ $# -eq 0 ]; then
+  DIRS=("$ROOT/specs/metrics" "$ROOT/specs/migrations")
+fi
 
 while [ $# -gt 0 ]; do
   case "$1" in
-    --dir) DIR="$2"; shift 2 ;;
-    --bundle) BUNDLE="$2"; shift 2 ;;
+    --dir)     DIRS+=("$2"); shift 2 ;;
+    --bundle)  BUNDLE="$2"; shift 2 ;;
     --help|-h) usage ;;
-    *) echo "validate-okf: unknown flag: $1" >&2; usage ;;
+    *)
+      echo "validate-okf: unknown flag: $1" >&2
+      echo "Run 'scripts/validate-okf.sh --help' for usage." >&2
+      exit 2
+      ;;
   esac
 done
 
 echo "validate-okf: scanning for OKF bundles..."
 
 if [ -n "$BUNDLE" ]; then
-  validate_bundle "$BUNDLE"
-elif [ -n "$DIR" ]; then
-  if [ ! -d "$DIR" ]; then
-    printf "${YELLOW}SKIP${NC} directory not found: %s\n" "$DIR"
-    exit 0
-  fi
-  count=0
-  while IFS= read -r -d '' f; do
-    # Only process .md files with YAML frontmatter
-    if head -1 "$f" 2>/dev/null | grep -q '^---$'; then
-      validate_bundle "$f"
-      count=$((count + 1))
-    fi
-  done < <(find "$DIR" -maxdepth 1 -name '*.md' -print0 2>/dev/null || true)
-  if [ "$count" -eq 0 ]; then
-    printf "${YELLOW}SKIP${NC} no OKF bundles found in %s\n" "$DIR"
-  else
-    echo "validate-okf: scanned $count bundle(s)"
+  if [ ! -f "$BUNDLE" ]; then
+    printf "${RED}FAIL${NC} bundle not found: %s\n" "$BUNDLE"
+    exit 1
   fi
+  validate_bundle "$BUNDLE"
+elif [ ${#DIRS[@]} -gt 0 ]; then
+  for d in "${DIRS[@]}"; do
+    scan_dir "$d"
+  done
 else
-  echo "validate-okf: nothing to validate" >&2
+  echo "validate-okf: nothing to validate (no --dir or --bundle)" >&2
+  exit 1
 fi
 
 exit "$EXIT_CODE"