bigpowers 2.73.3 → 2.73.5

package/scripts/lib/sync-post.sh

@@ -0,0 +1,162 @@
+#!/usr/bin/env bash
+# story: e13s03 e28s03
+# Post-sync pipeline for sync-skills.sh — manifests, lockfiles, guards, OKF wikis.
+# Args: $1=skill_count  $2=opencode_count (optional, default 0)
+
+if [ -n "${SYNC_POST_LOADED:-}" ]; then
+  return 0
+fi
+SYNC_POST_LOADED=1
+
+sync_post_run() {
+  local skill_count="${1:-0}"
+  local opencode_count="${2:-0}"
+  local pkg_version pkg_desc readme readme_tmp trace_mdc manifest ext_ver pkg_ver validate_script
+
+  pkg_version=$(jq -r '.version' "$REPO_ROOT/package.json")
+  pkg_desc=$(jq -r '.description' "$REPO_ROOT/package.json")
+
+  jq -n --arg name "bigpowers" \
+        --arg version "$pkg_version" \
+        --arg desc "${skill_count} skills — ${pkg_desc}" \
+        '{name: $name, version: $version, description: $desc}' > "$GEMINI_MANIFEST"
+
+  jq -n --arg version "$pkg_version" \
+        --arg desc "${skill_count} skills — ${pkg_desc}" \
+        '{
+          "name": "bigpowers",
+          "version": $version,
+          "description": $desc,
+          "keywords": ["pi-package"],
+          "pi": {
+            "skills": ["./skills"],
+            "prompts": ["./prompts"]
+          }
+        }' > "$PI_PACKAGE_JSON"
+
+  {
+    echo "{"
+    echo "  \"\$schema\": \"https://opencode.ai/config.json\","
+    echo "  \"instructions\": [\"CLAUDE.md\", \"CONVENTIONS.md\"]"
+    echo "}"
+  } > "$REPO_ROOT/opencode.json"
+
+  if [[ -x "$REPO_ROOT/scripts/regenerate-lockfile.sh" ]]; then
+    bash "$REPO_ROOT/scripts/regenerate-lockfile.sh" || {
+      echo "sync-skills: FAIL — lockfile regeneration failed" >&2
+      exit 1
+    }
+  fi
+
+  if [[ -x "$REPO_ROOT/scripts/generate-skill-index.sh" ]]; then
+    bash "$REPO_ROOT/scripts/generate-skill-index.sh" || {
+      echo "sync-skills: FAIL — SKILL-INDEX.md generation failed" >&2
+      exit 1
+    }
+  fi
+
+  if [[ -x "$REPO_ROOT/scripts/build-skill-index.sh" ]]; then
+    bash "$REPO_ROOT/scripts/build-skill-index.sh" || true
+  fi
+
+  local CURSOR_KEEP="context7.mdc" mdc mdc_base
+  for mdc in "$CURSOR_RULES"/*.mdc; do
+    [[ -e "$mdc" ]] || continue
+    mdc_base=$(basename "$mdc")
+    case " $CURSOR_KEEP " in *" $mdc_base "*) continue ;; esac
+    if [[ ! -f "$SKILLS_ROOT/${mdc_base%.mdc}/SKILL.md" ]]; then
+      rm "$mdc"
+      echo "  → pruned orphan cursor rule: $mdc_base"
+    fi
+  done
+
+  readme="$REPO_ROOT/README.md"
+  if [[ -f "$readme" ]] && grep -q 'badge/skills-' "$readme"; then
+    readme_tmp=$(mktemp)
+    sed -E "s|(badge/skills-)[0-9]+(-brightgreen)|\1${skill_count}\2|" "$readme" > "$readme_tmp"
+    mv "$readme_tmp" "$readme"
+  fi
+
+  echo "sync-skills: $skill_count skills synced"
+  echo "  → .cursor/rules/ ($skill_count .mdc files)"
+  echo "  → .gemini/extensions/bigpowers/skills/ (Agent Skills)"
+  echo "  → .gemini/extensions/bigpowers/commands/ (Slash Commands)"
+  echo "  → .gemini/extensions/bigpowers/gemini-extension.json"
+  echo "  → .pi/skills/ ($skill_count skill dirs — pi Agent Skills)"
+  echo "  → .pi/prompts/ ($skill_count prompt templates — pi slash commands)"
+  echo "  → .pi/package.json (pi package manifest)"
+  echo "  → skills-lock.json (catalog with SHA-256 hashes)"
+  echo "  → SKILL-INDEX.md (auto-generated skill reference)"
+  echo "  → opencode.json (CLAUDE.md + CONVENTIONS.md instructions)"
+  [[ -n "${OPN_TARGET:-}" ]] && echo "  → bigpowers-opencode: $opencode_count skills"
+
+  sync_post_regression_guards
+
+  if [[ -d "$REPO_ROOT/.git" ]]; then
+    bash "$REPO_ROOT/scripts/generate-reference-tables.sh"
+  fi
+
+  echo ""
+  echo "Generating OKF wikis..."
+  bash "$REPO_ROOT/scripts/generate-epics-wiki.sh"
+  bash "$REPO_ROOT/scripts/generate-adr-wiki.sh"
+  echo "sync-skills: OKF wikis regenerated"
+}
+
+sync_post_regression_guards() {
+  local trace_mdc manifest ext_ver pkg_ver validate_script
+
+  trace_mdc="$REPO_ROOT/.cursor/rules/trace-requirement.mdc"
+  if [[ -f "$trace_mdc" ]] && ! grep -q 'release-plan.yaml + epic' "$trace_mdc"; then
+    echo "sync-skills: FAIL — '+' missing from trace-requirement; use sed -E for whitespace collapse" >&2
+    exit 1
+  fi
+
+  manifest="$REPO_ROOT/.gemini/extensions/bigpowers/gemini-extension.json"
+  if [[ -f "$manifest" ]]; then
+    ext_ver=$(jq -r '.version // empty' "$manifest")
+    pkg_ver=$(jq -r '.version // empty' "$REPO_ROOT/package.json")
+    if [[ -n "$ext_ver" && -n "$pkg_ver" && "$ext_ver" != "$pkg_ver" ]]; then
+      echo "sync-skills: FAIL — gemini-extension.json version ($ext_ver) != package.json ($pkg_ver)" >&2
+      exit 1
+    fi
+  fi
+
+  validate_script="$REPO_ROOT/scripts/validate-skill-yaml.py"
+  if [[ -f "$validate_script" ]] && command -v $PYTHON &>/dev/null; then
+    if ! $PYTHON "$validate_script" > /dev/null 2>&1; then
+      echo "sync-skills: FAIL — YAML frontmatter validation failed" >&2
+      $PYTHON "$validate_script" >&2
+      exit 1
+    fi
+  fi
+
+  if grep -rn '^declare -A\|^[[:space:]]*declare -A' \
+      scripts/sync-skills.sh scripts/generate-skill-index.sh \
+      scripts/regenerate-lockfile.sh scripts/build-skill-index.sh 2>/dev/null; then
+    echo "sync-skills: FAIL — bash 4+ features detected in install-chain scripts (not macOS-compatible)" >&2
+    exit 1
+  fi
+}
+
+sync_opencode_copy() {
+  local opencode_count=0 skill_dir skill_md skill_name
+  SYNC_OPENCODE_COUNT=0
+
+  [[ -z "${OPN_TARGET:-}" || ! -d "$OPN_TARGET" ]] && return 0
+
+  echo ""
+  echo "Syncing skills to opencode repo: $OPN_TARGET"
+  OPN_SKILLS="$OPN_TARGET/skills"
+  mkdir -p "$OPN_SKILLS"
+  for skill_dir in "$SKILLS_ROOT"/*/; do
+    skill_md="$skill_dir/SKILL.md"
+    [[ -f "$skill_md" ]] || continue
+    skill_name=$(basename "$skill_dir")
+    mkdir -p "$OPN_SKILLS/$skill_name"
+    cp "$skill_md" "$OPN_SKILLS/$skill_name/SKILL.md"
+    opencode_count=$((opencode_count + 1))
+  done
+  echo "  → $opencode_count skills copied to $OPN_SKILLS/"
+  SYNC_OPENCODE_COUNT=$opencode_count
+}

package/scripts/lib/sync-render.sh

@@ -0,0 +1,126 @@
+#!/usr/bin/env bash
+# story: e13s03 e39s04
+# Render helpers for sync-skills.sh — build_body + per-target render_* functions.
+# Source after skill-common.sh; expects CURSOR_RULES, GEMINI_*, PI_*, OKF_WIKI_* globals.
+
+if [ -n "${SYNC_RENDER_LOADED:-}" ]; then
+  return 0
+fi
+SYNC_RENDER_LOADED=1
+
+build_body() {
+  local skill_md="$1"
+  local skill_dir="$2"
+  local body extra_md
+
+  body=$(awk '/^---/{f++; next} f>=2{print}' "$skill_md")
+  for extra_md in $(find "$skill_dir" -maxdepth 1 -name "*.md" ! -name "SKILL.md" | LC_ALL=C sort); do
+    body="$body"$'\n\n'"---"$'\n\n'"$(cat "$extra_md")"
+  done
+  echo "$body" | grep -v 'disable-model-invocation'
+}
+
+render_cursor() {
+  local cursor_file="$CURSOR_RULES/$IR_NAME.mdc"
+  {
+    echo "---"
+    echo "description: \"$IR_DESC_ESCAPED\""
+    echo "alwaysApply: false"
+    echo "---"
+    echo ""
+    echo "$IR_BODY"
+  } > "$cursor_file"
+}
+
+render_gemini_skill() {
+  mkdir -p "$GEMINI_SKILLS/$IR_NAME"
+  {
+    echo "---"
+    echo "name: $IR_NAME"
+    echo "description: \"$IR_DESC_ESCAPED\""
+    echo "---"
+    echo ""
+    echo "$IR_BODY"
+  } > "$GEMINI_SKILLS/$IR_NAME/SKILL.md"
+}
+
+render_gemini_command() {
+  mkdir -p "$GEMINI_COMMANDS/prompts"
+  local prompt_file="commands/prompts/$IR_NAME.md"
+  echo "$IR_BODY" > "$GEMINI_EXT_DIR/$prompt_file"
+  {
+    echo "description = \"$IR_DESC_ESCAPED\""
+    echo "prompt = \"@{$prompt_file}\""
+  } > "$GEMINI_COMMANDS/$IR_NAME.toml"
+}
+
+render_pi_skill() {
+  mkdir -p "$PI_SKILLS/$IR_NAME"
+  {
+    echo "---"
+    echo "name: $IR_NAME"
+    echo "description: \"$IR_DESC_ESCAPED\""
+    [[ -n "$IR_MODEL" ]] && echo "model: $IR_MODEL"
+    echo "---"
+    echo ""
+    echo "$IR_BODY"
+  } > "$PI_SKILLS/$IR_NAME/SKILL.md"
+}
+
+render_pi_prompt() {
+  {
+    echo "---"
+    echo "description: $IR_DESCRIPTION"
+    echo "---"
+    echo ""
+    echo "$IR_BODY"
+  } > "$PI_PROMPTS/$IR_NAME.md"
+}
+
+render_okf_concept() {
+  mkdir -p "$OKF_WIKI_SKILLS"
+  local okf_file="$OKF_WIKI_SKILLS/$IR_NAME.md"
+  local phase="utility" title desc_escaped short_desc effort_val="${_PF_EFFORT:-standard}"
+
+  case "$IR_NAME" in
+    survey-context|elaborate-spec|model-domain|define-language|\
+    design-interface|plan-work|plan-release|slice-tasks|\
+    kickoff-branch|develop-tdd|verify-work|audit-code|\
+    commit-message|release-branch|security-review|\
+    assess-impact|investigate-bug|validate-fix|dispatch-agents|\
+    request-review|respond-review|hook-commits|guard-git|\
+    wire-observability|wire-ci|smoke-test|deploy|enforce-first)
+      phase="critical-path" ;;
+  esac
+
+  title=$(echo "$IR_NAME" | sed -E 's/-/ /g; s/\b(.)/\U\1/g')
+  desc_escaped=$(echo "$IR_DESCRIPTION" | sed 's/\\/\\\\/g; s/"/\\"/g')
+  short_desc="$IR_DESCRIPTION"
+  [[ ${#short_desc} -gt 200 ]] && short_desc="${short_desc:0:197}..."
+
+  {
+    echo "---"
+    echo "okf_kind: concept"
+    echo "type: Skill"
+    echo "id: $IR_NAME"
+    echo "title: \"$title\""
+    echo "name: $IR_NAME"
+    echo "category: skills"
+    [[ -n "$IR_MODEL" ]] && echo "model: $IR_MODEL"
+    echo "effort: $effort_val"
+    echo "phase: $phase"
+    echo "description: \"$desc_escaped\""
+    echo "references: []"
+    echo "---"
+    echo ""
+    echo "# $title"
+    echo ""
+    echo "**Phase:** $phase"
+    [[ -n "$IR_MODEL" ]] && echo "**Model:** $IR_MODEL"
+    echo "**Effort:** $effort_val"
+    echo ""
+    echo "$IR_DESCRIPTION"
+    echo ""
+    echo "> Auto-generated by sync-skills.sh --okf (e39s04) from $SKILLS_ROOT/$IR_NAME/SKILL.md"
+  } > "$okf_file"
+}

package/scripts/lib/validate-okf-kinds.sh

@@ -0,0 +1,272 @@
+#!/usr/bin/env bash
+# story: e38s09 e41s04 e45s02
+# OKF kind-specific validators — sourced by validate-okf.sh
+
+if [ -n "${VALIDATE_OKF_KINDS_LOADED:-}" ]; then return 0; fi
+VALIDATE_OKF_KINDS_LOADED=1
+
+val_nullish() { [ -z "$1" ] || [ "$1" = "null" ] || [ "$1" = "None" ]; }
+val_nullish_or_empty() { val_nullish "$1" || [ "$1" = "[]" ]; }
+
+okf_parse_frontmatter() {
+  local file="$1"
+  $PYTHON -c "
+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:
+    sys.exit(1)
+try:
+    fm = yaml.safe_load(parts[1])
+    if fm is None:
+        sys.exit(1)
+    print(json.dumps(fm, cls=SafeEncoder))
+except Exception as e:
+    print(f'YAML parse error: {e}', file=sys.stderr)
+    sys.exit(1)
+" 2>/dev/null
+}
+
+validate_story_metrics() {
+  local file="$1" fm="$2" name="$3" errs=0 key val source generator commit_range eff
+  for key in id epic bcps commit_range source generated_at generator; do
+    val="$(echo "$fm" | $PYTHON -c "import json,sys; d=json.load(sys.stdin); print(d.get('$key',''))" 2>/dev/null)"
+    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; }
+
+  source="$(echo "$fm" | $PYTHON -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
+
+  generator="$(echo "$fm" | $PYTHON -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" "$name" "$generator"
+    EXIT_CODE=1; return
+  fi
+
+  commit_range="$(echo "$fm" | $PYTHON -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" "$name" "$commit_range"
+    EXIT_CODE=1; return
+  fi
+
+  eff="$(echo "$fm" | $PYTHON -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" errs=0 key val fp_count
+  for key in id title since_version order actions_needed; do
+    val="$(echo "$fm" | $PYTHON -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; }
+
+  fp_count="$(echo "$fm" | $PYTHON -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
+
+  printf "${GREEN}PASS${NC} %s (actions=%s, fingerprint has %s check(s))\n" \
+    "$name" \
+    "$(echo "$fm" | $PYTHON -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" count bad
+  count="$(echo "$fm" | $PYTHON -c "
+import json,sys
+d=json.load(sys.stdin)
+print(len(d.get('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
+
+  bad="$(echo "$fm" | $PYTHON -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"
+}
+
+validate_concept() {
+  local file="$1" fm="$2" name="$3" errs=0 key val ref_count cat
+  for key in id title category; do
+    val="$(echo "$fm" | $PYTHON -c "import json,sys; d=json.load(sys.stdin); print(d.get('$key',''))" 2>/dev/null)"
+    if val_nullish "$val"; then
+      printf "${RED}FAIL${NC} %s: missing required key '%s'\n" "$name" "$key"
+      errs=$((errs + 1))
+    fi
+  done
+  ref_count="$(echo "$fm" | $PYTHON -c "
+import json,sys
+d=json.load(sys.stdin)
+r=d.get('references',[])
+print(len(r) if isinstance(r,list) else 0)
+" 2>/dev/null)"
+  if [ "${ref_count:-0}" -eq 0 ]; then
+    printf "${RED}FAIL${NC} %s: references[] is empty or missing\n" "$name"
+    errs=$((errs + 1))
+  fi
+  [ "$errs" -gt 0 ] && { EXIT_CODE=1; return; }
+  cat="$(echo "$fm" | $PYTHON -c "import json,sys; d=json.load(sys.stdin); print(d.get('category',''))" 2>/dev/null)"
+  printf "${GREEN}PASS${NC} %s (category=%s, %s reference(s))\n" "$name" "$cat" "$ref_count"
+}
+
+validate_verification_report() {
+  local file="$1" fm="$2" name="$3" errs=0 key val gs score rc
+  for key in score gate_status threshold total_pass total_fail generated_by; do
+    val="$(echo "$fm" | $PYTHON -c "import json,sys; d=json.load(sys.stdin); print(d.get('$key',''))" 2>/dev/null)"
+    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; }
+
+  gs="$(echo "$fm" | $PYTHON -c "import json,sys; d=json.load(sys.stdin); print(d.get('gate_status',''))" 2>/dev/null)"
+  if ! echo "pass fail concerns waived" | grep -qw "$gs"; then
+    printf "${RED}FAIL${NC} %s: invalid gate_status '%s' — must be pass|fail|concerns|waived\n" "$name" "$gs"
+    EXIT_CODE=1; return
+  fi
+
+  score="$(echo "$fm" | $PYTHON -c "
+import json,sys
+d=json.load(sys.stdin)
+s=d.get('score')
+if s is None or not isinstance(s,(int,float)):
+    sys.exit(1)
+if s < 0 or s > 100:
+    sys.exit(2)
+print(s)
+" 2>/dev/null)" || {
+    rc=$?
+    if [ "$rc" -eq 1 ]; then printf "${RED}FAIL${NC} %s: score missing or not numeric\n" "$name"
+    else printf "${RED}FAIL${NC} %s: score out of bounds (0-100)\n" "$name"; fi
+    EXIT_CODE=1; return
+  }
+
+  printf "${GREEN}PASS${NC} %s (score=%.1f, gate=%s, threshold=%.1f)\n" \
+    "$name" "$score" "$gs" \
+    "$(echo "$fm" | $PYTHON -c "import json,sys; d=json.load(sys.stdin); print(d.get('threshold',0))" 2>/dev/null)"
+}
+
+validate_receipts() {
+  local f="$ROOT/specs/receipts.json"
+  if [ ! -f "$f" ]; then printf "${YELLOW}SKIP${NC} receipts.json not found\n"; return; fi
+  $PYTHON -c "
+import json, sys
+d=json.load(open('$f'))
+vs={'measured','estimated','backfilled','absent'}
+ss=('compliance','golden_suite','metrics','traceability')
+errs=0
+for sec in ss:
+    data=d.get(sec)
+    if data is None: continue
+    src=data.get('source','')
+    if not src: print(f'FAIL: receipts.json — {sec}: missing source tag'); errs+=1; continue
+    if src not in vs: print(f'FAIL: receipts.json — {sec}: unknown source \"{src}\"'); errs+=1; continue
+    hv='value' in data
+    if src=='absent' and hv: print(f'FAIL: receipts.json — {sec}: tagged absent but carries value'); errs+=1
+    elif src!='absent' and not hv: print(f'FAIL: receipts.json — {sec}: tagged {src} but missing value'); errs+=1
+if errs==0: print('PASS receipts.json')
+else: print(f'{errs} violation(s) in receipts.json')
+sys.exit(errs)
+" || { EXIT_CODE=1; return; }
+}
+
+validate_bundle() {
+  local file="$1" name fm fm_type kind
+  name="$(basename "$file")"
+  fm="$(okf_parse_frontmatter "$file")" || {
+    printf "${RED}FAIL${NC} %s: cannot parse YAML frontmatter\n" "$name"
+    EXIT_CODE=1
+    return
+  }
+
+  fm_type="$(echo "$fm" | $PYTHON -c "import json,sys; d=json.load(sys.stdin); print(d.get('type',''))" 2>/dev/null)"
+  if [ -z "$fm_type" ]; then
+    printf "${RED}FAIL${NC} %s: OKF v0.1 — missing required 'type' field\n" "$name"
+    EXIT_CODE=1
+    return
+  fi
+
+  if [ "$name" = "index.md" ] && [ "$fm_type" != "Index" ]; then
+    printf "${RED}FAIL${NC} %s: OKF v0.1 — index.md must have type: Index (got '%s')\n" "$name" "$fm_type"
+    EXIT_CODE=1
+    return
+  fi
+
+  kind="$(echo "$fm" | $PYTHON -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" ;;
+    concept)             validate_concept "$file" "$fm" "$name" ;;
+    verification-report) validate_verification_report "$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
+}
+
+okf_scan_dir() {
+  local dir="$1" count=0 f
+  if [ ! -d "$dir" ]; then
+    printf "${RED}FAIL${NC} directory not found: %s\n" "$dir"
+    EXIT_CODE=1
+    return
+  fi
+  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
+}

package/scripts/okf-add-references.py

@@ -0,0 +1,79 @@
+#!/usr/bin/env python3
+# story: e39s04
+"""Add cross-references from skill-graph.json into OKF concept files."""
+from __future__ import annotations
+
+import json
+import re
+import sys
+from pathlib import Path
+
+
+def main() -> int:
+    graph_json = Path(sys.argv[1])
+    wiki_skills = Path(sys.argv[2])
+
+    with open(graph_json, encoding="utf-8") as f:
+        graph = json.load(f)
+
+    edges = graph.get("edges", [])
+    nodes = {n.get("id") or n.get("name") for n in graph.get("nodes", [])}
+    nodes.discard(None)
+
+    refs: dict[str, list[dict[str, str]]] = {}
+    for edge in edges:
+        src = edge.get("from") or edge.get("source")
+        tgt = edge.get("to") or edge.get("target")
+        rel = edge.get("relationType") or edge.get("relation") or "references"
+        if src in nodes and tgt in nodes:
+            refs.setdefault(src, []).append({"concept": tgt, "type": rel})
+
+    skill_names = {f.stem for f in wiki_skills.glob("*.md")}
+    count_updated = 0
+
+    for path in wiki_skills.glob("*.md"):
+        name = path.stem
+        content = path.read_text(encoding="utf-8")
+        concept_refs = list(refs.get(name, []))
+
+        desc_match = re.search(r'description:\s*"(.*?)"', content, re.DOTALL)
+        if desc_match:
+            desc = desc_match.group(1)
+            for skill_name in skill_names:
+                if (
+                    skill_name != name
+                    and skill_name in desc
+                    and not any(r["concept"] == skill_name for r in concept_refs)
+                ):
+                    concept_refs.append({"concept": skill_name, "type": "references"})
+
+        seen: set[tuple[str, str]] = set()
+        unique_refs: list[dict[str, str]] = []
+        for ref in concept_refs:
+            key = (ref["concept"], ref["type"])
+            if key not in seen:
+                seen.add(key)
+                unique_refs.append(ref)
+
+        if unique_refs:
+            ref_lines = []
+            for ref in unique_refs:
+                ref_lines.append(f'  - concept: {ref["concept"]}')
+                ref_lines.append(f'    type: {ref["type"]}')
+            ref_block = "\n".join(ref_lines)
+            content = re.sub(r"references:\s*\[\]", f"references:\n{ref_block}", content)
+        else:
+            content = re.sub(
+                r"references:\s*\[\]",
+                "references:\n  - concept: skills-wiki\n    type: belongs_to",
+                content,
+            )
+        count_updated += 1
+        path.write_text(content, encoding="utf-8")
+
+    print(f"  concepts with cross-references: {count_updated}", file=sys.stderr)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())