bigpowers 2.50.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/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"

package/scripts/wait-for-ci.sh

@@ -0,0 +1,130 @@
+#!/usr/bin/env bash
+# wait-for-ci.sh — Poll GitHub Actions until all workflow runs complete
+# Usage: wait-for-ci.sh [--timeout SECONDS] [--interval SECONDS] [--branch BRANCH]
+#   --timeout   Max seconds to wait (default: 600)
+#   --interval  Seconds between polls (default: 30)
+#   --branch    Branch to check (default: current branch)
+#   --commit    Specific commit SHA to verify (default: HEAD)
+#   --json      Output machine-readable JSON on completion
+#   --help      Show this message
+#
+# Exit codes: 0 = all workflows green, 1 = any workflow failed, 2 = timeout, 3 = no gh CLI
+
+set -euo pipefail
+
+TIMEOUT=600
+INTERVAL=30
+BRANCH=$(git branch --show-current 2>/dev/null || echo "main")
+COMMIT=""
+OUTPUT_JSON=false
+
+usage() {
+  sed -n '2,12p' "$0" | sed 's/^# //'
+}
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --timeout) TIMEOUT="$2"; shift 2 ;;
+    --interval) INTERVAL="$2"; shift 2 ;;
+    --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 ;;
+  esac
+done
+
+COMMIT="${COMMIT:-$(git rev-parse HEAD)}"
+COMMIT_SHORT="${COMMIT:0:7}"
+
+# ── Git-only fallback ─────────────────────────────────────────────────
+if ! command -v gh >/dev/null 2>&1; then
+  echo "⚠️  gh CLI not found — using git-only fallback (cannot verify CI status)"
+  git fetch origin "$BRANCH" 2>/dev/null || true
+  REMOTE_SHA=$(git rev-parse "origin/$BRANCH" 2>/dev/null || echo "")
+  if [[ -n "$REMOTE_SHA" ]] && [[ "$REMOTE_SHA" == "$COMMIT" ]]; then
+    echo "✅ Push confirmed: remote $BRANCH matches $COMMIT_SHORT"
+    echo "⚠️  CI status UNVERIFIED — gh CLI required for workflow polling"
+    exit 0
+  else
+    echo "❌ Push unconfirmed: remote $BRANCH does not match $COMMIT_SHORT"
+    exit 1
+  fi
+fi
+
+# ── Verify gh auth ────────────────────────────────────────────────────
+if ! gh auth status 2>/dev/null; then
+  echo "⚠️  gh CLI not authenticated — falling back to git-only"
+  git fetch origin "$BRANCH" 2>/dev/null || true
+  REMOTE_SHA=$(git rev-parse "origin/$BRANCH" 2>/dev/null || echo "")
+  if [[ -n "$REMOTE_SHA" ]] && [[ "$REMOTE_SHA" == "$COMMIT" ]]; then
+    echo "✅ Push confirmed: remote $BRANCH matches $COMMIT_SHORT"
+    echo "⚠️  CI status UNVERIFIED — gh auth required for workflow polling"
+    exit 0
+  else
+    echo "❌ Push unconfirmed"
+    exit 1
+  fi
+fi
+
+# ── Poll CI ───────────────────────────────────────────────────────────
+REPO=$(gh repo view --json nameWithOwner -q .nameWithOwner 2>/dev/null || echo "unknown")
+echo "==> Polling CI for $BRANCH ($COMMIT_SHORT) in $REPO"
+echo "    Timeout: ${TIMEOUT}s, Interval: ${INTERVAL}s"
+
+ELAPSED=0
+FAILED_WORKFLOWS=()
+PASSED_WORKFLOWS=()
+
+while [[ $ELAPSED -lt $TIMEOUT ]]; do
+  # Fetch all runs for the branch
+  RUNS_JSON=$(gh run list --branch "$BRANCH" --limit 20 --json workflowName,status,conclusion,headSha,databaseId,displayTitle 2>/dev/null || echo "[]")
+
+  # Filter to runs matching our commit
+  MATCHING_RUNS=$(echo "$RUNS_JSON" | jq --arg sha "$COMMIT" '[.[] | select(.headSha == $sha)]' 2>/dev/null || echo "[]")
+
+  RUN_COUNT=$(echo "$MATCHING_RUNS" | jq 'length' 2>/dev/null || echo "0")
+
+  if [[ "$RUN_COUNT" -eq 0 ]]; then
+    echo "  (${ELAPSED}s) No runs found for $COMMIT_SHORT — waiting for CI to start..."
+    sleep "$INTERVAL"
+    ELAPSED=$((ELAPSED + INTERVAL))
+    continue
+  fi
+
+  # Check completion
+  INCOMPLETE=$(echo "$MATCHING_RUNS" | jq '[.[] | select(.status != "completed")] | length' 2>/dev/null || echo "0")
+  FAILURES=$(echo "$MATCHING_RUNS" | jq '[.[] | select(.status == "completed" and .conclusion == "failure")]' 2>/dev/null || echo "[]")
+  FAILURE_COUNT=$(echo "$FAILURES" | jq 'length' 2>/dev/null || echo "0")
+  SUCCESSES=$(echo "$MATCHING_RUNS" | jq '[.[] | select(.status == "completed" and .conclusion == "success")]' 2>/dev/null || echo "[]")
+  SUCCESS_COUNT=$(echo "$SUCCESSES" | jq 'length' 2>/dev/null || echo "0")
+
+  echo "  (${ELAPSED}s) $RUN_COUNT runs: $SUCCESS_COUNT passed, $FAILURE_COUNT failed, $INCOMPLETE pending"
+
+  # All complete?
+  if [[ "$INCOMPLETE" -eq 0 ]]; then
+    if [[ "$FAILURE_COUNT" -eq 0 ]]; then
+      echo "✅ All $SUCCESS_COUNT workflow(s) passed for $COMMIT_SHORT"
+      if $OUTPUT_JSON; then
+        echo "$SUCCESSES" | jq '{status:"success",commit:$sha,workflows:.}' --arg sha "$COMMIT_SHORT"
+      fi
+      exit 0
+    else
+      echo "❌ $FAILURE_COUNT workflow(s) FAILED:"
+      echo "$FAILURES" | jq -r '.[] | "    \(.workflowName) — https://github.com/'"$REPO"'/actions/runs/\(.databaseId)"'
+      echo ""
+      echo "Handoff: set handoff.next_skill = fix-bug in specs/state.yaml"
+      if $OUTPUT_JSON; then
+        echo "$FAILURES" | jq '{status:"failure",commit:$sha,failed_workflows:.}' --arg sha "$COMMIT_SHORT"
+      fi
+      exit 1
+    fi
+  fi
+
+  sleep "$INTERVAL"
+  ELAPSED=$((ELAPSED + INTERVAL))
+done
+
+echo "❌ Timeout: CI did not complete within ${TIMEOUT}s"
+echo "    Branch: $BRANCH, Commit: $COMMIT_SHORT"
+exit 2

package/skills/align-grid/SKILL.md

@@ -2,6 +2,7 @@
 name: align-grid
 description: "Build editorial/magazine/report webpages on a GENUINE Müller-Brockmann modular grid (International Typographic Style) — not a decorative one. Encodes the discipline (columns + modules + baseline, grotesque type, flush-left, restrained black/white/red palette) AND the hard-won front-end engineering to make the grid real, visible, and verified: one CSS-variable source of truth, an interactive grid-toggle overlay that lives in the SAME content box as the content, subgrid \"bands\" so every element snaps to a column line, an 8px baseline lock, and runtime OPTICAL ALIGNMENT that puts display type's ink (not its box) on the line. Ships with a scaffold generator and a Puppeteer verification harness that proves 0px adherence."
 model: sonnet
+effort: standard
 ---
 
 # Müller-Brockmann Grid Systems — built real, visible, and verified