bigpowers 2.58.1 → 2.58.3

package/scripts/validate-okf.sh

@@ -1,59 +1,58 @@
 #!/usr/bin/env bash
-#
-# validate-okf.sh — provenance gate for OKF story-metrics bundles (e40/e31 style).
-#
-# A 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.
-#
-# 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
-#
+# story: e38s09
+# validate-okf.sh — kind-aware, fail-closed provenance gate for OKF bundles.
+# Validates story-metrics, spec-migration, and migration-registry bundles.
+# Multi-dir default: specs/metrics/ + specs/migrations/.
 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'
 
-usage() {
+usage_okf() {
   cat <<'EOF'
 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).
+# ---- Helpers ------------------------------------------------------------
+
+# True if value is empty, null JSON literal, or Python None string.
+val_nullish() { [ -z "$1" ] || [ "$1" = "null" ] || [ "$1" = "None" ]; }
+
+# True if value is nullish OR the JSON empty array literal.
+val_nullish_or_empty() { val_nullish "$1" || [ "$1" = "[]" ]; }
+
+# ---- 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 +61,223 @@ 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
+  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
+    if val_nullish "$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; }
 
-  # 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
+
+  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 val_nullish_or_empty "$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=""
 
-[ $# -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 ;;
-    --help|-h) usage ;;
-    *) echo "validate-okf: unknown flag: $1" >&2; usage ;;
+    --dir)     DIRS+=("$2"); shift 2 ;;
+    --bundle)  BUNDLE="$2"; shift 2 ;;
+    --help|-h) usage_okf ;;
+    *)
+      echo "validate-okf: unknown flag: $1" >&2
+      echo "Run 'scripts/validate-okf.sh --help' for help." >&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"

package/scripts/wait-for-ci.sh

@@ -18,7 +18,7 @@ BRANCH=$(git branch --show-current 2>/dev/null || echo "main")
 COMMIT=""
 OUTPUT_JSON=false
 
-usage() {
+usage_ci() {
   sed -n '2,12p' "$0" | sed 's/^# //'
 }
 
@@ -29,8 +29,8 @@ while [[ $# -gt 0 ]]; do
     --branch) BRANCH="$2"; shift 2 ;;
     --commit) COMMIT="$2"; shift 2 ;;
     --json) OUTPUT_JSON=true; shift ;;
-    --help) usage; exit 0 ;;
-    *) echo "Unknown flag: $1"; usage; exit 2 ;;
+    --help) usage_ci; exit 0 ;;
+    *) echo "Unknown flag: $1"; usage_ci; exit 2 ;;
   esac
 done