bigpowers 2.73.3 → 2.73.5

package/.pi/package.json

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

package/.pi/prompts/gate-trace.md

@@ -1,5 +1,5 @@
 ---
-description: "Deterministic traceability quality gate — reads coverage matrix + blind-spot data, applies decision rules with oracle confidence downgrade, emits PASS/CONCERNS/FAIL/WAIVED verdict. Use before release-branch to gate merges on traceability." # story: e38s06
+description: "Deterministic traceability quality gate — reads coverage matrix + blind-spot data, applies decision rules with oracle confidence downgrade, emits PASS/CONCERNS/FAIL/WAIVED verdict. Use before release-branch to gate merges on traceability."
 ---
 
 

package/.pi/prompts/maintain-wiki.md

@@ -1,5 +1,5 @@
 ---
-description: "Agent-maintained OKF wiki — INGEST source docs, LINT for issues, QUERY across concept pages. Run as part of build-epic Step 8 and verify-work Phase 3." # story: e39s07
+description: "Agent-maintained OKF wiki — INGEST source docs, LINT for issues, QUERY across concept pages. Run as part of build-epic Step 8 and verify-work Phase 3."
 ---
 
 

package/.pi/prompts/security-review.md

@@ -1,5 +1,5 @@
 ---
-description: >   AI-powered security analysis of code changes — traces data flow, detects   injection, auth bypass, secrets exposure, and unsafe deserialization across   files. Use when reviewing pending changes, before release-branch, during   verify-work Phase 5, during build-epic Step 0 threat modeling, or when   the user says "security review" or "scan for vulns".
+description: >
 ---
 
 

package/.pi/skills/gate-trace/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: gate-trace
-description: "\"Deterministic traceability quality gate — reads coverage matrix + blind-spot data, applies decision rules with oracle confidence downgrade, emits PASS/CONCERNS/FAIL/WAIVED verdict. Use before release-branch to gate merges on traceability.\" # story: e38s06"
+description: "\"Deterministic traceability quality gate — reads coverage matrix + blind-spot data, applies decision rules with oracle confidence downgrade, emits PASS/CONCERNS/FAIL/WAIVED verdict. Use before release-branch to gate merges on traceability.\""
 model: haiku
 ---
 

package/.pi/skills/maintain-wiki/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: maintain-wiki
-description: "\"Agent-maintained OKF wiki — INGEST source docs, LINT for issues, QUERY across concept pages. Run as part of build-epic Step 8 and verify-work Phase 3.\" # story: e39s07"
+description: "\"Agent-maintained OKF wiki — INGEST source docs, LINT for issues, QUERY across concept pages. Run as part of build-epic Step 8 and verify-work Phase 3.\""
 model: haiku
 ---
 

package/.pi/skills/security-review/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: security-review
-description: ">   AI-powered security analysis of code changes — traces data flow, detects   injection, auth bypass, secrets exposure, and unsafe deserialization across   files. Use when reviewing pending changes, before release-branch, during   verify-work Phase 5, during build-epic Step 0 threat modeling, or when   the user says \"security review\" or \"scan for vulns\"."
+description: ">"
 model: sonnet
 ---
 

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+## [2.73.5](https://github.com/danielvm-git/bigpowers/compare/v2.73.4...v2.73.5) (2026-07-06)
+
+
+### Bug Fixes
+
+* **verify:** split golden suite and validate-okf into lib modules ([#60](https://github.com/danielvm-git/bigpowers/issues/60)) ([d0c1a7a](https://github.com/danielvm-git/bigpowers/commit/d0c1a7ae8811b37d532471a9eb758936964344f4))
+
+## [2.73.4](https://github.com/danielvm-git/bigpowers/compare/v2.73.3...v2.73.4) (2026-07-06)
+
+
+### Bug Fixes
+
+* **sync:** split sync-skills.sh into lib modules under 300-line cap ([#59](https://github.com/danielvm-git/bigpowers/issues/59)) ([eed704f](https://github.com/danielvm-git/bigpowers/commit/eed704fe87a9f89dec211bbc6c6695afee884e52))
+
 ## [2.73.3](https://github.com/danielvm-git/bigpowers/compare/v2.73.2...v2.73.3) (2026-07-06)
 
 

package/package.json

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

package/scripts/lib/golden-suite-agent.sh

@@ -0,0 +1,80 @@
+#!/usr/bin/env bash
+# story: e42s04
+# Agent-driven golden story runner — sourced by golden-suite-run.sh
+
+if [ -n "${GOLDEN_AGENT_LOADED:-}" ]; then return 0; fi
+GOLDEN_AGENT_LOADED=1
+
+golden_run_agent_stories() {
+  local yaml_file story_id PASS_K PASS_THRESHOLD story_pass story_fail flake_note LOCK_FILE
+
+  AGENT_PASS=0 AGENT_FAIL=0 AGENT_SKIP=0 AGENT_FLAKE=0 AGENT_TOTAL=0
+  AGENT_RESULTS=()
+  DETERMINISTIC_PASSED=false
+  [[ "$FAIL_COUNT" -eq 0 ]] && DETERMINISTIC_PASSED=true
+
+  if ! $AGENT_MODE; then return 0; fi
+  if ! $DETERMINISTIC_PASSED; then
+    echo ""
+    echo -e "${GOLDEN_YELLOW}── Agent stories skipped: deterministic gates failed ──${GOLDEN_NC}"
+    AGENT_RESULTS+=("  status: skipped" "  reason: deterministic gates failed")
+    return 0
+  fi
+
+  echo ""
+  echo "── Agent-Driven Golden Stories ──"
+
+  if [[ ! -d "$GOLDEN_DIR" ]]; then
+    echo -e "${GOLDEN_YELLOW}WARN: $GOLDEN_DIR not found — agent stories skipped${GOLDEN_NC}"
+    AGENT_RESULTS+=("  status: skipped" "  reason: golden directory not found")
+    (( AGENT_SKIP += 1 ))
+    return 0
+  fi
+
+  for yaml_file in "$GOLDEN_DIR"/g-*.yaml; do
+    [[ -f "$yaml_file" ]] || continue
+    story_id=$(basename "$yaml_file" .yaml)
+    echo -n "[$story_id] "
+
+    PASS_K=$($PYTHON -c "import yaml; d=yaml.safe_load(open('$yaml_file')); print(d.get('pass_at_k',{}).get('k',3))" 2>/dev/null || echo 3)
+    PASS_THRESHOLD=$($PYTHON -c "import yaml; d=yaml.safe_load(open('$yaml_file')); print(d.get('pass_at_k',{}).get('threshold',2))" 2>/dev/null || echo 2)
+
+    story_pass=0 story_fail=0
+    LOCK_FILE=".github/workflows/e42-golden-deepseek.lock.yml"
+
+    for ((attempt=1; attempt<=PASS_K; attempt++)); do
+      if [[ ! -f "$LOCK_FILE" ]]; then
+        echo -e "${GOLDEN_YELLOW}SKIP${GOLDEN_NC} (no compiled workflow for $story_id)"
+        break
+      fi
+      if $PYTHON -c "
+import yaml
+d = yaml.safe_load(open('$yaml_file'))
+assert d.get('grader',{}).get('type') == 'code', 'grader must be code'
+assert d['grader'].get('command'), 'grader command required'
+assert d.get('pass_at_k',{}).get('k') == $PASS_K
+assert d['pass_at_k'].get('threshold') == $PASS_THRESHOLD
+" 2>/dev/null; then
+        (( story_pass += 1 ))
+      else
+        (( story_fail += 1 ))
+      fi
+    done
+
+    if [[ "$story_pass" -eq 0 && "$story_fail" -eq 0 ]]; then
+      echo -e "${GOLDEN_YELLOW}SKIP${GOLDEN_NC}"
+      AGENT_RESULTS+=("  - id: $story_id" "    status: skipped" "    pass_at_k: \"0/$PASS_K\"")
+      (( AGENT_SKIP += 1 ))
+    elif [[ "$story_pass" -ge "$PASS_THRESHOLD" ]]; then
+      flake_note=""
+      [[ "$story_fail" -gt 0 ]] && flake_note=" (flake: $story_fail)" && (( AGENT_FLAKE += story_fail ))
+      echo -e "${GOLDEN_GREEN}PASS${GOLDEN_NC}${flake_note} (pass@k: $story_pass/$PASS_K)"
+      AGENT_RESULTS+=("  - id: $story_id" "    status: pass" "    pass_at_k: \"$story_pass/$PASS_K\"" "    flake_count: $story_fail")
+      (( AGENT_PASS += 1 ))
+    else
+      echo -e "${GOLDEN_RED}FAIL${GOLDEN_NC} (pass@k: $story_pass/$PASS_K, threshold $PASS_THRESHOLD)"
+      AGENT_RESULTS+=("  - id: $story_id" "    status: fail" "    pass_at_k: \"$story_pass/$PASS_K\"" "    flake_count: $story_fail")
+      (( AGENT_FAIL += 1 ))
+    fi
+  done
+}

package/scripts/lib/golden-suite-gates.sh

@@ -0,0 +1,105 @@
+#!/usr/bin/env bash
+# story: e42s04 e45s02
+# Deterministic gate runner for golden suite — sourced by golden-suite-run.sh
+
+if [ -n "${GOLDEN_GATES_LOADED:-}" ]; then return 0; fi
+GOLDEN_GATES_LOADED=1
+
+GOLDEN_GATES=(
+  "compliance:npm run compliance:false"
+  "g04-selftest:bash scripts/golden-g04-selftest.sh:true"
+  "g06-migrate-version:bash tests/run-golden-migrate-version.sh:true"
+  "g07-negative-path:bash scripts/golden-g07-negative-path.sh:false"
+  "g08-anti-vacuity:bash scripts/golden-g08-anti-vacuity.sh:false"
+  "g09-yaml-roundtrip:bash scripts/golden-g09-yaml-roundtrip.sh:false"
+  "g10-trace-anti-vacuity:bash scripts/golden-g10-trace-anti-vacuity.sh:false"
+  "g11-gitignore-venv:bash scripts/golden-g11-gitignore-venv.sh:false"
+  "specs-parse:bash scripts/validate-specs-yaml.sh:false"
+)
+
+GOLDEN_GREEN='\033[0;32m'
+GOLDEN_RED='\033[0;31m'
+GOLDEN_YELLOW='\033[0;33m'
+GOLDEN_NC='\033[0m'
+
+golden_agent_dry_run() {
+  local yaml_count=0 yaml_ok=0 yaml_fail=0 yaml_file story_id
+
+  echo "Agent Golden Stories — DRY RUN"
+  echo "Golden YAML directory: $GOLDEN_DIR"
+
+  if [[ ! -d "$GOLDEN_DIR" ]]; then
+    echo -e "${GOLDEN_YELLOW}WARN: $GOLDEN_DIR not found${GOLDEN_NC}"
+    return 0
+  fi
+
+  for yaml_file in "$GOLDEN_DIR"/g-*.yaml; do
+    [[ -f "$yaml_file" ]] || continue
+    (( yaml_count += 1 ))
+    story_id=$(basename "$yaml_file" .yaml)
+
+    if $PYTHON -c "import yaml; yaml.safe_load(open('$yaml_file'))" 2>/dev/null; then
+      local grader_type pass_k
+      grader_type=$($PYTHON -c "import yaml; d=yaml.safe_load(open('$yaml_file')); print(d.get('grader',{}).get('type',''))" 2>/dev/null)
+      pass_k=$($PYTHON -c "import yaml; d=yaml.safe_load(open('$yaml_file')); pk=d.get('pass_at_k',{}); print(f\"{pk.get('k',0)}-of-{pk.get('threshold',0)}\")" 2>/dev/null)
+      echo -e "  ${GOLDEN_GREEN}OK${GOLDEN_NC}   $story_id — grader=$grader_type, pass@k=$pass_k"
+      (( yaml_ok += 1 ))
+    else
+      echo -e "  ${GOLDEN_RED}FAIL${GOLDEN_NC} $story_id — YAML parse error"
+      (( yaml_fail += 1 ))
+    fi
+  done
+
+  echo ""
+  echo "Agent YAML validation: $yaml_ok/$yaml_count parseable"
+  if [[ "$yaml_fail" -gt 0 ]]; then
+    echo -e "${GOLDEN_RED}$yaml_fail YAML(s) failed to parse${GOLDEN_NC}"
+    return 1
+  fi
+  return 0
+}
+
+golden_run_deterministic_gates() {
+  local gate name cmd is_optional main_cmd script_path
+  PASS_COUNT=0 FAIL_COUNT=0 SKIP_COUNT=0
+  GATE_RESULTS=()
+
+  for gate in "${GOLDEN_GATES[@]}"; do
+    IFS=':' read -r name cmd is_optional <<< "$gate"
+    echo -n "[$name] "
+
+    main_cmd=$(echo "$cmd" | awk '{print $1}')
+    if [[ "$main_cmd" == "bash" ]]; then
+      script_path=$(echo "$cmd" | awk '{print $2}')
+      if [[ ! -f "$script_path" ]]; then
+        if [[ "$is_optional" == "true" ]]; then
+          echo -e "${GOLDEN_YELLOW}SKIP${GOLDEN_NC} (script not yet implemented)"
+          GATE_RESULTS+=("  - name: $name" "    exit_code: skipped" "    duration_seconds: 0" "    status: skipped" "    note: script not found: $script_path")
+          (( SKIP_COUNT += 1 ))
+          continue
+        fi
+        echo -e "${GOLDEN_RED}FAIL${GOLDEN_NC} (script not found: $script_path)"
+        GATE_RESULTS+=("  - name: $name" "    exit_code: 127" "    duration_seconds: 0" "    status: fail" "    error: script not found: $script_path")
+        (( FAIL_COUNT += 1 ))
+        continue
+      fi
+    fi
+
+    local START_TIME END_TIME DURATION_MS DURATION_SEC GATE_EXIT
+    START_TIME=$(date +%s%N)
+    eval "$cmd" >/dev/null 2>&1 && GATE_EXIT=$? || GATE_EXIT=$?
+    END_TIME=$(date +%s%N)
+    DURATION_MS=$(( (END_TIME - START_TIME) / 1000000 ))
+    DURATION_SEC=$(echo "scale=2; $DURATION_MS / 1000" | bc 2>/dev/null || echo "0")
+
+    if [[ "$GATE_EXIT" -eq 0 ]]; then
+      echo -e "${GOLDEN_GREEN}PASS${GOLDEN_NC} (${DURATION_SEC}s)"
+      GATE_RESULTS+=("  - name: $name" "    exit_code: 0" "    duration_seconds: $DURATION_SEC" "    status: pass")
+      (( PASS_COUNT += 1 ))
+    else
+      echo -e "${GOLDEN_RED}FAIL${GOLDEN_NC} (${DURATION_SEC}s, exit $GATE_EXIT)"
+      GATE_RESULTS+=("  - name: $name" "    exit_code: $GATE_EXIT" "    duration_seconds: $DURATION_SEC" "    status: fail")
+      (( FAIL_COUNT += 1 ))
+    fi
+  done
+}

package/scripts/lib/golden-suite-report.sh

@@ -0,0 +1,157 @@
+#!/usr/bin/env bash
+# story: e31s04 e45s02
+# Golden suite reporting — verdict, YAML/OKF output, size budget
+
+if [ -n "${GOLDEN_REPORT_LOADED:-}" ]; then return 0; fi
+GOLDEN_REPORT_LOADED=1
+
+golden_compute_verdict() {
+  TOTAL=$((PASS_COUNT + FAIL_COUNT + SKIP_COUNT))
+  AGENT_TOTAL=$((AGENT_PASS + AGENT_FAIL + AGENT_SKIP))
+  if [[ "$FAIL_COUNT" -gt 0 || "$AGENT_FAIL" -gt 0 ]]; then OVERALL="fail"; else OVERALL="pass"; fi
+}
+
+golden_print_verdict() {
+  golden_compute_verdict
+  echo ""
+  echo "══════════════════════════════════════════"
+  echo "           GOLDEN SUITE VERDICT"
+  echo "══════════════════════════════════════════"
+  echo ""
+  echo "Deterministic gates:"
+  echo -e "  ${PASS_COUNT}/${TOTAL} passed"
+  [[ "$SKIP_COUNT" -gt 0 ]] && echo -e "  ${SKIP_COUNT} skipped"
+  [[ "$FAIL_COUNT" -gt 0 ]] && echo -e "  ${GOLDEN_RED}${FAIL_COUNT} failed${GOLDEN_NC}"
+
+  if $AGENT_MODE; then
+    echo ""
+    echo "Agent-driven stories:"
+    echo -e "  ${AGENT_PASS}/${AGENT_TOTAL} passed"
+    [[ "$AGENT_FAIL" -gt 0 ]] && echo -e "  ${GOLDEN_RED}${AGENT_FAIL} failed${GOLDEN_NC}"
+    [[ "$AGENT_SKIP" -gt 0 ]] && echo -e "  ${AGENT_SKIP} skipped"
+    [[ "$AGENT_FLAKE" -gt 0 ]] && echo -e "  ${GOLDEN_YELLOW}${AGENT_FLAKE} flake(s) detected${GOLDEN_NC} (absorbed by pass@k 2-of-3)"
+  fi
+
+  echo ""
+  echo -e "Combined verdict: $([[ "$OVERALL" == "pass" ]] && echo -e "${GOLDEN_GREEN}PASS${GOLDEN_NC}" || echo -e "${GOLDEN_RED}FAIL${GOLDEN_NC}")"
+  echo "Report: $REPORT_FILE"
+  echo "══════════════════════════════════════════"
+}
+
+golden_write_reports() {
+  local PASS_RATE AGENT_PASS_RATE OKF_DIR OKF_FILE THRESHOLD GATE_STATUS mode
+
+  PASS_RATE=$(echo "scale=2; $PASS_COUNT / $TOTAL" | bc 2>/dev/null || echo "0")
+  AGENT_PASS_RATE="n/a"
+  [[ "$AGENT_TOTAL" -gt 0 ]] && AGENT_PASS_RATE=$(echo "scale=2; $AGENT_PASS / $AGENT_TOTAL" | bc 2>/dev/null || echo "0")
+  mode=$([ "$BASELINE_MODE" = true ] && echo 'baseline' || echo 'daily')
+
+  cat > "$REPORT_FILE" << YAML_EOF
+timestamp: "$TIMESTAMP"
+git_commit: "$GIT_COMMIT"
+suite: "golden-combined"
+mode: "$mode"
+deterministic:
+  total: $TOTAL
+  passed: $PASS_COUNT
+  failed: $FAIL_COUNT
+  skipped: $SKIP_COUNT
+  pass_rate: $PASS_RATE
+gates:
+$(printf '%s\n' "${GATE_RESULTS[@]}")
+agent_stories:
+  total: $AGENT_TOTAL
+  passed: $AGENT_PASS
+  failed: $AGENT_FAIL
+  skipped: $AGENT_SKIP
+  flake_count: $AGENT_FLAKE
+  pass_rate: $AGENT_PASS_RATE
+summary:
+  combined_verdict: "$OVERALL"
+YAML_EOF
+
+  OKF_DIR="specs/verifications/reports"
+  mkdir -p "$OKF_DIR"
+  OKF_FILE="$OKF_DIR/GOLDEN-${TODAY}.okf.md"
+  THRESHOLD=100
+  GATE_STATUS="$OVERALL"
+
+  cat > "$OKF_FILE" << OKF_EOF
+---
+okf_kind: verification-report
+okf_version: "0.1"
+score: ${PASS_RATE}
+gate_status: "${GATE_STATUS}"
+threshold: ${THRESHOLD}
+total_pass: ${PASS_COUNT}
+total_fail: ${FAIL_COUNT}
+total_skip: ${SKIP_COUNT}
+generated_by: ${GOLDEN_GENERATED_BY}
+generated_at: "${TIMESTAMP}"
+git_commit: "${GIT_COMMIT}"
+---
+
+# Golden Suite — ${TODAY}
+
+**Score:** ${PASS_RATE} (${PASS_COUNT}/${TOTAL} passed)
+**Gate:** ${GATE_STATUS} | **Threshold:** ${THRESHOLD}%
+
+See \`${REPORT_FILE}\` for the full YAML report.
+OKF_EOF
+
+  echo "OKF report: $OKF_FILE"
+}
+
+golden_write_baseline_sizes() {
+  local skill_md skill_name skill_bytes
+  echo "" >> "$REPORT_FILE"
+  echo "# Skill byte counts (baseline for e31s04 size budget)" >> "$REPORT_FILE"
+  echo "skill_sizes:" >> "$REPORT_FILE"
+  for skill_md in skills/*/SKILL.md; do
+    skill_name=$(basename "$(dirname "$skill_md")")
+    skill_bytes=$(wc -c < "$skill_md" | tr -d ' ')
+    echo "  $skill_name: $skill_bytes" >> "$REPORT_FILE"
+  done
+  echo "Baseline pinned: $REPORT_FILE"
+}
+
+golden_check_size_budget() {
+  local WARN_THRESHOLD=20 FAIL_THRESHOLD=50 skill_md skill_name current_bytes baseline_bytes pct
+  local SIZE_WARNINGS=0 SIZE_FAILURES=0 NEW_SKILLS=0
+
+  if [[ ! -f "$BASELINE_FILE" ]]; then
+    echo "No baseline found. Run --baseline first."
+    return 1
+  fi
+
+  echo ""
+  echo "Size Budget Check (+${WARN_THRESHOLD}% warn, +${FAIL_THRESHOLD}% fail):"
+  for skill_md in skills/*/SKILL.md; do
+    skill_name=$(basename "$(dirname "$skill_md")")
+    current_bytes=$(wc -c < "$skill_md" | tr -d ' ')
+    baseline_bytes=$(grep "^  $skill_name:" "$BASELINE_FILE" 2>/dev/null | awk '{print $2}')
+
+    if [[ -z "$baseline_bytes" ]]; then
+      echo -e "  ${GOLDEN_YELLOW}NEW${GOLDEN_NC}  $skill_name: ${current_bytes}b (not in baseline)"
+      (( NEW_SKILLS += 1 )) || true
+      continue
+    fi
+    [[ "$baseline_bytes" -eq 0 ]] && baseline_bytes=1
+    pct=$(( (current_bytes - baseline_bytes) * 100 / baseline_bytes ))
+
+    if [[ "$pct" -ge "$FAIL_THRESHOLD" ]]; then
+      echo -e "  ${GOLDEN_RED}FAIL${GOLDEN_NC} $skill_name: ${current_bytes}b (+${pct}%)"
+      (( SIZE_FAILURES += 1 )) || true
+    elif [[ "$pct" -ge "$WARN_THRESHOLD" ]]; then
+      echo -e "  ${GOLDEN_YELLOW}WARN${GOLDEN_NC} $skill_name: ${current_bytes}b (+${pct}%)"
+      (( SIZE_WARNINGS += 1 )) || true
+    else
+      echo -e "  ${GOLDEN_GREEN}OK${GOLDEN_NC}   $skill_name: ${current_bytes}b"
+    fi
+  done
+
+  echo ""
+  echo "Size summary: $SIZE_WARNINGS warnings, $SIZE_FAILURES failures, $NEW_SKILLS new"
+  [[ "$SIZE_FAILURES" -gt 0 ]] && return 1
+  return 0
+}

package/scripts/lib/golden-suite-run.sh

@@ -0,0 +1,79 @@
+#!/usr/bin/env bash
+# story: e42s04 e45s02
+# Golden suite orchestrator — sourced by run-verification-gates.sh / run-golden-suite.sh
+
+if [ -n "${GOLDEN_SUITE_RUN_LOADED:-}" ]; then return 0; fi
+GOLDEN_SUITE_RUN_LOADED=1
+
+_LIB="$(dirname "${BASH_SOURCE[0]}")"
+source "$_LIB/golden-suite-gates.sh"
+source "$_LIB/golden-suite-agent.sh"
+source "$_LIB/golden-suite-report.sh"
+
+golden_suite_main() {
+  local arg gate name cmd optional
+
+  REPORT_DIR="specs/benchmarks/reports"
+  BASELINE_FILE="$REPORT_DIR/BASELINE-GOLDEN.yaml"
+  GOLDEN_DIR="specs/benchmarks/golden"
+  DRY_RUN=false BASELINE_MODE=false CHECK_SIZE=false AGENT_MODE=false
+
+  for arg in "$@"; do
+    case "$arg" in
+      --dry-run) DRY_RUN=true ;;
+      --baseline) BASELINE_MODE=true ;;
+      --check-size) CHECK_SIZE=true ;;
+      --agent) AGENT_MODE=true ;;
+      *)
+        echo "Unknown flag: $arg"
+        echo "Usage: ${GOLDEN_USAGE_NAME} [--agent] [--dry-run] [--baseline] [--check-size]"
+        exit 2
+        ;;
+    esac
+  done
+
+  if $AGENT_MODE && ! command -v gh-aw &>/dev/null && ! command -v gh &>/dev/null; then
+    echo -e "${GOLDEN_YELLOW}WARNING: gh-aw not installed — agent gate skipped${GOLDEN_NC}" >&2
+    AGENT_MODE=false
+  fi
+
+  if $DRY_RUN; then
+    if $AGENT_MODE; then
+      echo "Golden Suite — DRY RUN (deterministic + agent)"
+      echo ""
+      echo "Deterministic gates (in order):"
+      for gate in "${GOLDEN_GATES[@]}"; do
+        IFS=':' read -r name cmd optional <<< "$gate"
+        echo "  - $name: $cmd"
+      done
+      echo ""
+      golden_agent_dry_run
+      exit $?
+    fi
+    echo "Golden Suite — DRY RUN"
+    echo "Gates (in order):"
+    for gate in "${GOLDEN_GATES[@]}"; do
+      IFS=':' read -r name cmd optional <<< "$gate"
+      echo "  - $name: $cmd"
+    done
+    echo "Report: $REPORT_DIR/GOLDEN-YYYY-MM-DD.yaml"
+    echo "OK (dry run)"
+    exit 0
+  fi
+
+  mkdir -p "$REPORT_DIR"
+  TODAY=$(date +%Y-%m-%d)
+  TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+  GIT_COMMIT=$(git rev-parse HEAD 2>/dev/null || echo "unknown")
+  if $BASELINE_MODE; then REPORT_FILE="$BASELINE_FILE"; else REPORT_FILE="$REPORT_DIR/GOLDEN-${TODAY}.yaml"; fi
+
+  golden_run_deterministic_gates
+  golden_run_agent_stories
+  golden_print_verdict
+  golden_write_reports
+
+  if $BASELINE_MODE; then golden_write_baseline_sizes; fi
+  if $CHECK_SIZE; then golden_check_size_budget; exit $?; fi
+  [[ "$OVERALL" == "fail" ]] && exit 1
+  exit 0
+}

package/scripts/lib/skill-common.sh

@@ -91,6 +91,27 @@ parse_frontmatter() {
   export SKILL_NAME SKILL_MODEL SKILL_DESC _PF_NAME _PF_MODEL _PF_DESCRIPTION
 }
 
+# parse_frontmatter_okf — like parse_frontmatter but also extracts effort field
+parse_frontmatter_okf() {
+  local file="$1"
+  _PF_EFFORT=""
+
+  if [[ ! -f "$file" ]] || ! grep -q '^---$' "$file"; then
+    return 1
+  fi
+
+  _PF_NAME=$(awk '/^---/{f++} f==1 && /^name:/{print; exit}' "$file" | sed 's/^name:[[:space:]]*//')
+  _PF_MODEL=$(awk '/^---/{f++} f==1 && /^model:/{print; exit}' "$file" | sed 's/^model:[[:space:]]*//')
+  _PF_EFFORT=$(awk '/^---/{f++} f==1 && /^effort:/{print; exit}' "$file" | sed 's/^effort:[[:space:]]*//')
+  _PF_DESCRIPTION=$(awk '/^---/{f++; next} f==1 && /^description:/{p=1; sub(/^description:[[:space:]]*/,""); print; next} f==1 && p && /^[a-z]+:/{exit} f==1 && p{print}' "$file" \
+    | tr -d '\n' \
+    | sed -E 's/[[:space:]]+/ /g')
+
+  [[ -z "$_PF_NAME" ]] && return 1
+  export _PF_NAME _PF_MODEL _PF_EFFORT _PF_DESCRIPTION
+  return 0
+}
+
 # iterate_skills — list skill directories containing SKILL.md, stable sorted order
 iterate_skills() {
   resolve_repo_root 2>/dev/null || true