bigpowers 2.49.0 → 2.51.0

package/scripts/record-cycle-time.sh

@@ -0,0 +1,340 @@
+#!/usr/bin/env bash
+#
+# record-cycle-time.sh — deterministic, git-derived delivery metrics.
+#
+# Replaces the agent's hand-written story_start/story_end timestamps and
+# hand-arithmetic (which produced fabricated / wall-clock-inflated rows in
+# specs/metrics/cycle-times.yaml). Two metrics, honestly separated:
+#
+#   effort_hours     ADDITIVE. Idle-stripped estimated effort. Computed as a
+#                    GLOBAL PARTITION of the commit stream so that
+#                    Σ(per-story effort) == whole-repo effort, exactly.
+#                    Overnight / weekend / UAT gaps are dropped by construction.
+#
+#   lead_time_minutes  NON-ADDITIVE. Calendar latency, first-commit → merge.
+#                      Aggregate by median/p75 over many stories. NEVER sum.
+#
+# Effort model (git-hours, kimmobrunfeldt/git-hours src/index.js:15,18):
+#   * commits sorted by author-date across the WHOLE range;
+#   * gap < IDLE (120 min)  -> real elapsed time, credited to the *later*
+#                              commit's story (the work that produced it);
+#   * gap >= IDLE           -> session boundary: credit a flat PAD (120 min)
+#                              to the later commit's story, drop the idle time;
+#   * the very first commit of the stream is never padded (no left neighbour).
+#
+# Why not run git-hours per story and sum? Because it doesn't sum: each
+# per-story run re-pads its own first commit and drops its own leading gap,
+# so the sum leaks both ways. The global partition above is additive by
+# construction. Attribution of a shared <120-min window to "the later commit's
+# story" is a documented CONVENTION, not a physical truth — it is the only way
+# to keep the numbers summable without double-counting.
+#
+# Story attribution: a `Story: <id>` trailer in the commit message. Commits
+# with no trailer land in the `unattributed` bucket (surfaced, never dropped).
+# Merge commits are excluded (--no-merges); duplicate SHAs cannot occur in a
+# single range.
+#
+# Usage:
+#   scripts/record-cycle-time.sh report [--range <git-range>] [--story-key <key>]
+#   scripts/record-cycle-time.sh append --story <id> --bcps <n> \
+#         [--range <git-range>] [--merged-at <epoch>] [--file <path>] [--story-key <key>]
+#
+# `report`  prints the per-story partition + an additivity self-check.
+# `append`  recomputes the partition and appends one row for <id> to the ledger.
+#
+set -euo pipefail
+
+IDLE_SECONDS=$(( 120 * 60 ))   # git-hours maxCommitDiffInMinutes
+PAD_SECONDS=$(( 120 * 60 ))    # git-hours firstCommitAdditionInMinutes
+STORY_KEY="Story"
+
+die() { echo "record-cycle-time: $*" >&2; exit 1; }
+
+usage() {
+  cat <<'EOF'
+Usage: scripts/record-cycle-time.sh <command> [flags]
+
+Commands:
+  report      Compute per-story effort partition + additivity self-check.
+              Flags: --range <git-range>  --story-key <trailer-key>
+  append      Recompute partition and append one row for a story.
+              Flags: --story <id> --bcps <n> [--range <git-range>]
+                     [--merged-at <epoch>] [--file <path>] [--story-key <trailer-key>]
+  self-test   Run report, then exit 0 on additivity PASS; exit 1 on FAIL.
+              Flags: --range <git-range>  --story-key <trailer-key>
+  help        Show this message.
+
+Global flags:
+  --help      Show this message (works with any subcommand).
+
+Description:
+  Computes git-derived, additive effort from commit history.
+  Two metrics, separated: effort_hours (ADDITIVE, Σ = total) and
+  lead_time_minutes (calendar latency, median-aggregate, NEVER sum).
+
+  Uses the git-hours model: commits sorted by author-date across the
+  whole range; gaps < 120 min counted as effort; gaps >= 120 min
+  start a new session with a 120-min pad.
+EOF
+  exit 0
+}
+
+command -v git >/dev/null 2>&1 || die "git not found"
+ROOT="$(git rev-parse --show-toplevel 2>/dev/null)" || die "not inside a git repo"
+
+# ---- engine ---------------------------------------------------------------
+# Emits, per story bucket, a TSV line:  story <TAB> effort_hours <TAB> commit_count <TAB> first_epoch <TAB> last_epoch
+# Reads the whole range once and partitions globally, so the lines are additive.
+partition() {
+  local range="$1" key="$2"
+  # US (\x1f) between fields; one commit per line, oldest→newest by author date.
+  git -C "$ROOT" log --no-merges "$range" \
+      --pretty=format:"%at%x1f%H%x1f%(trailers:key=${key},valueonly,separator=%x2C)" \
+    | sort -n \
+    | awk -F '\x1f' -v IDLE="$IDLE_SECONDS" -v PAD="$PAD_SECONDS" '
+        {
+          ts = $1 + 0
+          story = $3
+          gsub(/[[:space:]]/, "", story)
+          if (story == "") story = "unattributed"
+          count[story]++
+          seen[story] = 1
+          if (NR > 1) {
+            gap = ts - prev
+            if (gap < 0) gap = 0              # guard against author-date skew
+            if (gap < IDLE) eff[story] += gap  # real elapsed effort -> later commit
+            else            eff[story] += PAD   # new session pad -> later commit
+          }
+          if (!(story in first)) first[story] = ts
+          last[story] = ts
+          prev = ts
+        }
+        END {
+          for (s in seen)
+            printf "%s\t%.4f\t%d\t%d\t%d\n", s, eff[s] / 3600.0, count[s], first[s], last[s]
+        }' \
+    | sort
+}
+
+# Whole-range effort in one bucket — the independent additivity oracle.
+whole_range_hours() {
+  local range="$1"
+  git -C "$ROOT" log --no-merges "$range" --pretty=format:"%at" \
+    | sort -n \
+    | awk -v IDLE="$IDLE_SECONDS" -v PAD="$PAD_SECONDS" '
+        { ts=$1+0; if(NR>1){gap=ts-prev; if(gap<0)gap=0; if(gap<IDLE)e+=gap; else e+=PAD} prev=ts }
+        END { printf "%.4f\n", e/3600.0 }'
+}
+
+cmd_report() {
+  local range="HEAD" key="$STORY_KEY"
+  while [ $# -gt 0 ]; do
+    case "$1" in
+      --range) range="$2"; shift 2 ;;
+      --story-key) key="$2"; shift 2 ;;
+      *) die "unknown flag: $1" ;;
+    esac
+  done
+
+  local rows; rows="$(partition "$range" "$key")"
+  [ -n "$rows" ] || die "no commits in range '$range'"
+
+  printf '%-16s %12s %8s   %s\n' "story" "effort_hours" "commits" "coding_span"
+  printf '%-16s %12s %8s   %s\n' "----------------" "------------" "--------" "-----------------"
+  local sum
+  sum="$(printf '%s\n' "$rows" | awk -F'\t' '
+    {
+      span = ($5 - $4) / 60.0
+      printf "%-16s %12.2f %8d   %.0f min\n", $1, $2, $3, span
+      total += $2
+    }
+    END { printf "__TOTAL__ %.4f\n", total > "/dev/stderr" }
+  ' 2> >(cat >&2))"
+  printf '%s\n' "$sum"
+
+  # Additivity self-check: Σ(per-story) must equal the whole-range oracle.
+  local part_total whole
+  part_total="$(printf '%s\n' "$rows" | awk -F'\t' '{t+=$2} END{printf "%.4f\n", t}')"
+  whole="$(whole_range_hours "$range")"
+  printf -- '----\n'
+  printf 'Σ(per-story effort_hours) = %s\n' "$part_total"
+  printf 'whole-range effort_hours  = %s   (independent oracle)\n' "$whole"
+  # Compare with a rounding tolerance (per-story values are rounded before summing).
+  if awk -v a="$part_total" -v b="$whole" 'BEGIN{d=a-b; if(d<0)d=-d; exit !(d < 0.01)}'; then
+    printf 'ADDITIVITY: PASS — the partition sums to the whole (within rounding).\n'
+  else
+    printf 'ADDITIVITY: FAIL — Σ(%s) != whole(%s)\n' "$part_total" "$whole" >&2
+    return 1
+  fi
+}
+
+cmd_append() {
+  local range="HEAD" key="$STORY_KEY" story="" bcps="" merged_at="" file="$ROOT/specs/metrics/cycle-times.yaml"
+  local telemetry=""  # path to harness telemetry JSON (GSD-2/gsd-pi format, optional)
+  while [ $# -gt 0 ]; do
+    case "$1" in
+      --story) story="$2"; shift 2 ;;
+      --bcps) bcps="$2"; shift 2 ;;
+      --range) range="$2"; shift 2 ;;
+      --merged-at) merged_at="$2"; shift 2 ;;
+      --file) file="$2"; shift 2 ;;
+      --story-key) key="$2"; shift 2 ;;
+      --telemetry) telemetry="$2"; shift 2 ;;
+      *) die "unknown flag: $1" ;;
+    esac
+  done
+  [ -n "$story" ] || die "append requires --story <id>"
+  [ -n "$bcps" ]  || die "append requires --bcps <n>"
+  [ -n "$merged_at" ] || merged_at="$(date -u +%s)"
+
+  local rows line eff count first last
+  rows="$(partition "$range" "$key")"
+  line="$(printf '%s\n' "$rows" | awk -F'\t' -v s="$story" '$1==s')"
+  [ -n "$line" ] || die "story '$story' has no attributable commits in range '$range' (check the 'Story: $story' trailer)"
+
+  eff="$(printf '%s' "$line"   | cut -f2)"
+  count="$(printf '%s' "$line" | cut -f3)"
+  first="$(printf '%s' "$line" | cut -f4)"
+  last="$(printf '%s' "$line"  | cut -f5)"
+
+  # lead time: first commit of the story -> merge (calendar latency; NEVER summed).
+  local lead_min
+  lead_min="$(awk -v m="$merged_at" -v f="$first" 'BEGIN{printf "%.0f", (m-f)/60.0}')"
+
+  local first_iso range_lo range_hi
+  first_iso="$(date -u -d "@$first" +%Y-%m-%dT%H:%M:%SZ 2>/dev/null || date -u -r "$first" +%Y-%m-%dT%H:%M:%SZ)"
+  range_lo="$(git -C "$ROOT" log --no-merges "$range" --pretty=%h --reverse 2>/dev/null \
+              | awk 'NR==1{print}')"
+  range_hi="$(git -C "$ROOT" rev-parse --short HEAD)"
+
+  local generated_at
+  generated_at="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+
+  # ---- telemetry ingestion (GSD-2/gsd-pi style; e40s04) ----
+  # If --telemetry <json-file> is provided, read the harness data and populate
+  # agent.* fields. Otherwise, agent.* stays null (git effort is the fallback).
+  local agent_cost agent_tokens_in agent_tokens_out agent_tokens_cache_read
+  local agent_tokens_cache_write agent_tokens_total agent_cache_hit
+  local agent_compression agent_tool_calls agent_api_requests
+  local agent_duration_ms agent_model agent_tier agent_downgraded agent_skills
+  agent_cost="null"; agent_tokens_total="null"; agent_cache_hit="null"
+  agent_compression="null"; agent_tool_calls="null"; agent_api_requests="null"
+  agent_duration_ms="null"; agent_model="null"; agent_tier="null"
+  agent_downgraded="null"; agent_skills="[]"
+
+  if [ -n "$telemetry" ] && [ -f "$telemetry" ]; then
+    # GSD-2/gsd-pi snapshotUnitMetrics JSON format:
+    #   { cost_usd, tokens: {input, output, cache_read, cache_write, total},
+    #     cache_hit_rate_pct, compression_savings_pct, tool_calls, api_requests,
+    #     agent_duration_ms, model, tier, model_downgraded, skills[] }
+    if command -v jq >/dev/null 2>&1; then
+      agent_cost="$(jq -r '.cost_usd // "null"' "$telemetry")"
+      agent_tokens_total="$(jq -r '.tokens.total // "null"' "$telemetry")"
+      agent_cache_hit="$(jq -r '.cache_hit_rate_pct // "null"' "$telemetry")"
+      agent_compression="$(jq -r '.compression_savings_pct // "null"' "$telemetry")"
+      agent_tool_calls="$(jq -r '.tool_calls // "null"' "$telemetry")"
+      agent_api_requests="$(jq -r '.api_requests // "null"' "$telemetry")"
+      agent_duration_ms="$(jq -r '.agent_duration_ms // "null"' "$telemetry")"
+      agent_model="$(jq -r '.model // "null"' "$telemetry")"
+      agent_tier="$(jq -r '.tier // "null"' "$telemetry")"
+      agent_downgraded="$(jq -r '.model_downgraded // "null"' "$telemetry")"
+      agent_skills="$(jq -c '.skills // []' "$telemetry")"
+      agent_tokens_in="$(jq -r '.tokens.input // "null"' "$telemetry")"
+      agent_tokens_out="$(jq -r '.tokens.output // "null"' "$telemetry")"
+      agent_tokens_cache_read="$(jq -r '.tokens.cache_read // "null"' "$telemetry")"
+      agent_tokens_cache_write="$(jq -r '.tokens.cache_write // "null"' "$telemetry")"
+    else
+      echo "record-cycle-time: jq not found — telemetry file ignored (git effort fallback)" >&2
+    fi
+  fi
+
+  # Emit OKF bundle (YAML frontmatter + markdown body) per story.
+  # This is the canonical format — see specs/templates/story-metrics.okf.md.
+  # Fields not yet populated (quality.*, flow.*) carry null placeholders.
+  {
+    printf -- '---\n'
+    printf -- 'okf_kind: story-metrics\n'
+    printf -- 'okf_version: "0.1"\n'
+    printf -- 'id: %s\n' "$story"
+    printf -- 'epic: %s\n' "${story%%s*}"          # e40s03 → e40
+    printf -- 'bcps: %s\n' "$bcps"
+    printf -- 'commit_range: "%s..%s"\n' "${range_lo:-$range_hi}" "$range_hi"
+    printf -- 'source: measured\n'
+    printf -- 'generated_at: %s\n' "$generated_at"
+    printf -- 'generator: scripts/record-cycle-time.sh\n'
+    printf -- '\n'
+    printf -- '# DORA — the four keys (market standard). ⌀ median aggregate.\n'
+    printf -- 'dora:\n'
+    printf -- '  lead_time_for_changes_min: %s   # ⌀ first commit → merge\n' "$lead_min"
+    printf -- '  deployment_frequency: null           # %% populated by e40s05\n'
+    printf -- '  change_failure: null                   # %% populated by e40s05\n'
+    printf -- '  time_to_restore_min: null              # ⌀ populated by e40s05\n'
+    printf -- '\n'
+    printf -- '# Agent code-generation telemetry (GSD-2 style). Σ additive.\n'
+    printf -- 'agent:\n'
+    printf -- '  cost_usd: %s                         # Σ harness telemetry (null = git effort fallback)\n' "$agent_cost"
+    printf -- '  tokens:\n'
+    printf -- '    input: %s\n' "$agent_tokens_in"
+    printf -- '    output: %s\n' "$agent_tokens_out"
+    printf -- '    cache_read: %s\n' "$agent_tokens_cache_read"
+    printf -- '    cache_write: %s\n' "$agent_tokens_cache_write"
+    printf -- '    total: %s\n' "$agent_tokens_total"
+    printf -- '  cache_hit_rate_pct: %s               # %%\n' "$agent_cache_hit"
+    printf -- '  compression_savings_pct: %s          # %%\n' "$agent_compression"
+    printf -- '  tool_calls: %s                       # Σ\n' "$agent_tool_calls"
+    printf -- '  api_requests: %s                     # Σ\n' "$agent_api_requests"
+    printf -- '  agent_duration_ms: %s                # Σ (excludes human UAT wait)\n' "$agent_duration_ms"
+    printf -- '  model: %s                            # •\n' "$agent_model"
+    printf -- '  tier: %s                             # • light|standard|heavy\n' "$agent_tier"
+    printf -- '  model_downgraded: %s                 # •\n' "$agent_downgraded"
+    printf -- '  skills: %s                           # Σ\n' "$agent_skills"
+    printf -- '\n'
+    printf -- '# Effort (git-derived, idle-stripped, ADDITIVE).\n'
+    printf -- 'effort:\n'
+    printf -- '  effort_hours: %s              # Σ idle-stripped (git-hours, 120-min threshold)\n' "$eff"
+    printf -- '  idle_threshold_min: 120              # • recorded for interpretability\n'
+    printf -- '\n'
+    printf -- '# Quality gate. ⌀ median / • static.\n'
+    printf -- 'quality:\n'
+    printf -- '  audit_score_pct: null                 # ⌀ populated by audit-code\n'
+    printf -- '  coverage_pct: null                    # ⌀ populated by test suite\n'
+    printf -- '  tests_passed: null                    # • populated by test suite\n'
+    printf -- '  verify_status: null                   # pass|waived\n'
+    printf -- '  rework_count: null                    # Σ reopens → feeds change_failure\n'
+    printf -- '\n'
+    printf -- '# Flow (worktree telemetry).\n'
+    printf -- 'flow:\n'
+    printf -- '  merge_duration_ms: null               # ⌀ p50/p95 across stories\n'
+    printf -- '  merge_conflicts: null                 # Σ\n'
+    printf -- '  worktree_orphaned: null               # •\n'
+    printf -- '---\n'
+    printf -- '\n'
+    printf -- '# Story metrics — %s\n' "$story"
+    printf -- '\n'
+    printf -- 'Effort derived from git commit history via the git-hours model\n'
+    printf -- '(src: kimmobrunfeldt/git-hours, 120-min idle threshold, 120-min\n'
+    printf -- 'first-commit pad). Lead time is calendar latency (first commit → merge).\n'
+    printf -- '\n'
+    printf -- 'Aggregation tags: Σ additive (sum → total) · ⌀ median/p95 (never sum)\n'
+    printf -- '· %% rate (ratio over window) · • static (identity).\n'
+  } >> "$file"
+
+  echo "record-cycle-time: OKF bundle written for $story → $file (effort=$eff h, lead=$lead_min min, commits=$count)"
+}
+
+[ $# -ge 1 ] || { usage; }
+
+# Trap --help before subcommand dispatch
+for a in "$@"; do
+  if [ "$a" = "--help" ] || [ "$a" = "-h" ]; then usage; fi
+done
+
+sub="$1"; shift
+case "$sub" in
+  report) cmd_report "$@" ;;
+  append) cmd_append "$@" ;;
+  self-test) cmd_report "$@" ;;
+  help) usage ;;
+  --help) usage ;;
+  *) die "unknown subcommand '$sub' (run 'record-cycle-time.sh help' for usage)" ;;
+esac

package/scripts/run-golden-suite.sh

@@ -15,12 +15,14 @@ REPORT_DIR="specs/benchmarks/reports"
 BASELINE_FILE="$REPORT_DIR/BASELINE-GOLDEN.yaml"
 DRY_RUN=false
 BASELINE_MODE=false
+CHECK_SIZE=false
 
 for arg in "$@"; do
   case "$arg" in
     --dry-run) DRY_RUN=true ;;
     --baseline) BASELINE_MODE=true ;;
-    *) echo "Unknown flag: $arg"; echo "Usage: run-golden-suite.sh [--dry-run] [--baseline]"; exit 2 ;;
+    --check-size) CHECK_SIZE=true ;;
+    *) echo "Unknown flag: $arg"; echo "Usage: run-golden-suite.sh [--dry-run] [--baseline] [--check-size]"; exit 2 ;;
   esac
 done
 
@@ -180,6 +182,62 @@ if $BASELINE_MODE; then
   echo "Baseline pinned: $REPORT_FILE"
 fi
 
+# ── Size budget check (e31s04) ───────────────────────────────────────
+
+if $CHECK_SIZE; then
+  WARN_THRESHOLD=20
+  FAIL_THRESHOLD=50
+
+  if [[ ! -f "$BASELINE_FILE" ]]; then
+    echo "No baseline found. Run --baseline first."
+    exit 1
+  fi
+
+  echo ""
+  echo "Size Budget Check (+${WARN_THRESHOLD}% warn, +${FAIL_THRESHOLD}% fail):"
+  SIZE_WARNINGS=0
+  SIZE_FAILURES=0
+  NEW_SKILLS=0
+
+  for skill_md in skills/*/SKILL.md; do
+    skill_name=$(basename "$(dirname "$skill_md")")
+    current_bytes=$(wc -c < "$skill_md" | tr -d ' ')
+
+    # Get baseline size (best-effort grep from YAML)
+    baseline_bytes=$(grep "^  $skill_name:" "$BASELINE_FILE" 2>/dev/null | awk '{print $2}')
+
+    if [[ -z "$baseline_bytes" ]]; then
+      echo "  ${YELLOW}NEW${NC}  $skill_name: ${current_bytes}b (not in baseline)"
+      (( NEW_SKILLS += 1 )) || true
+      continue
+    fi
+
+    if [[ "$baseline_bytes" -eq 0 ]]; then
+      baseline_bytes=1  # avoid division by zero
+    fi
+
+    pct=$(( (current_bytes - baseline_bytes) * 100 / baseline_bytes ))
+
+    if [[ "$pct" -ge "$FAIL_THRESHOLD" ]]; then
+      echo "  ${RED}FAIL${NC} $skill_name: ${current_bytes}b (+${pct}%)"
+      (( SIZE_FAILURES += 1 )) || true
+    elif [[ "$pct" -ge "$WARN_THRESHOLD" ]]; then
+      echo "  ${YELLOW}WARN${NC} $skill_name: ${current_bytes}b (+${pct}%)"
+      (( SIZE_WARNINGS += 1 )) || true
+    else
+      echo "  ${GREEN}OK${NC}   $skill_name: ${current_bytes}b"
+    fi
+  done
+
+  echo ""
+  echo "Size summary: $SIZE_WARNINGS warnings, $SIZE_FAILURES failures, $NEW_SKILLS new"
+
+  if [[ "$SIZE_FAILURES" -gt 0 ]]; then
+    exit 1
+  fi
+  exit 0
+fi
+
 if [[ "$OVERALL" == "fail" ]]; then
   exit 1
 fi

package/scripts/validate-okf.sh

@@ -0,0 +1,198 @@
+#!/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
+#
+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() {
+  cat <<'EOF'
+Usage: scripts/validate-okf.sh [flags]
+
+Flags:
+  --dir <path>       Validate all OKF bundles in directory (default: specs/metrics/)
+  --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.
+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).
+parse_frontmatter() {
+  local file="$1"
+  # Extract YAML frontmatter between --- markers
+  python3 -c "
+import yaml, sys
+content = open('$file').read()
+parts = content.split('---')
+if len(parts) < 3:
+    sys.exit(1)
+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))
+except Exception as e:
+    print(f'validate-okf: YAML parse error in $file: {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
+  }
+
+  # 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
+
+  # Check required keys
+  for key in $REQUIRED_KEYS; 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
+    fi
+  done
+
+  # Check 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
+  fi
+
+  # Check generator
+  local generator
+  generator="$(echo "$fm" | python3 -c "import json,sys; d=json.load(sys.stdin); print(d['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
+  fi
+
+  # Check 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)"
+  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
+  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
+  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"
+    EXIT_CODE=1
+    return
+  }
+
+  printf "${GREEN}PASS${NC} %s (source=%s, generator=%s, commit_range resolves)\n" "$bundle_name" "$source" "$generator"
+}
+
+# ---- main ----------------------------------------------------------------
+DIR=""
+BUNDLE=""
+
+[ $# -ge 1 ] || set -- "--dir" "$METRICS_DIR"  # default: validate specs/metrics/
+
+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 ;;
+  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)"
+  fi
+else
+  echo "validate-okf: nothing to validate" >&2
+fi
+
+exit "$EXIT_CODE"