bigpowers 2.73.2 → 2.73.4

package/.pi/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bigpowers",
-  "version": "2.73.2",
+  "version": "2.73.4",
   "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.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)
+
+
+### Bug Fixes
+
+* **trace:** trim trace-stories.py under 300-line cap ([879bb8a](https://github.com/danielvm-git/bigpowers/commit/879bb8a87940a4bf337dfed7406359f744e09a31))
+
 ## [2.73.2](https://github.com/danielvm-git/bigpowers/compare/v2.73.1...v2.73.2) (2026-07-06)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bigpowers",
-  "version": "2.73.2",
+  "version": "2.73.4",
   "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/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

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/trace-stories.py

@@ -8,10 +8,7 @@ Usage: called by scripts/trace-stories.sh with positional args:
   python3 scripts/lib/trace-stories.py <repo_root> <matrix_json> <trace_md>
       <okf_dir> <strict> <mode>
 
-Oracle tiers (TEA-inspired):
-  Tier 1: explicit story tag → confidence high
-  Tier 2: file-name heuristic match → confidence medium
-  Tier 3: epic capsule task reference → confidence low
+Oracle tiers: Tier 1 explicit tag (high), Tier 2 file heuristic (medium), Tier 3 task ref (low).
 """
 
 import json, os, re, subprocess, sys
@@ -26,9 +23,7 @@ OKF_DIR = Path(sys.argv[4])
 STRICT = int(sys.argv[5])
 MODE = sys.argv[6]
 
-# -----------------------------------------------------------------------
-# 1. Parse YAML files → story inventory
-# -----------------------------------------------------------------------
+# --- 1. Parse YAML files → story inventory
 _MIN_STORY_BASELINE = 50  # floor assertion: --strict FAILs if story count drops below this
 _STRICT_UNIMPLEMENTED_STATUSES = frozenset({"backlog", "todo", "planned"})
 
@@ -45,9 +40,7 @@ release = _load_yaml(ROOT / "specs" / "release-plan.yaml")
 exec_status = _load_yaml(ROOT / "specs" / "execution-status.yaml")
 dev_status = exec_status.get("development_status", {})
 
-# -----------------------------------------------------------------------
-# 2. Build story inventory
-# -----------------------------------------------------------------------
+# --- 2. Build story inventory
 stories: dict[str, dict] = {}
 epics = release.get("epics", [])
 if not isinstance(epics, list):
@@ -82,9 +75,7 @@ for epic in epics:
                         "bcp": s.get("bcp", 0), "wsjf": float(ewsjf),
                         "description": s.get("description", "")}
 
-# -----------------------------------------------------------------------
-# 3. Grep codebase for story tags
-# -----------------------------------------------------------------------
+# --- 3. Grep codebase for story tags
 result = subprocess.run(
     ["grep", "-rn", "--include=*.md", "--include=*.sh", "--include=*.py",
      "--include=*.js", "--include=*.ts", "--include=*.yaml", "--include=*.yml",
@@ -104,9 +95,7 @@ for line in result.stdout.splitlines():
         tagged_sids.add(sid)
         tag_index.setdefault(sid, []).append({"file": fpath, "line": fline})
 
-# -----------------------------------------------------------------------
-# 4. Oracle tiers
-# -----------------------------------------------------------------------
+# --- 4. Oracle tiers
 EXCLUDE_DIRS = {".git", "node_modules", ".cursor", ".gemini", ".pi", ".venv", "venv", ".tox", "__pycache__", "site-packages", ".mypy_cache", ".pytest_cache", ".ruff_cache"}
 EXCLUDE_PREFIXES = ("specs/archive/", "specs/codebase-wiki/")
 
@@ -177,9 +166,7 @@ for sid, sinfo in sorted(stories.items()):
 orphan_tags = [sid for sid in sorted(tagged_sids) if sid not in stories]
 stale_tags = [sid for sid in sorted(tagged_sids) if sid in stories and dev_status.get(sid) == "done"]
 
-# -----------------------------------------------------------------------
-# 5. Emit matrix JSON
-# -----------------------------------------------------------------------
+# --- 5. Emit matrix JSON
 matrix = {
     "generated_at": datetime.now(timezone.utc).isoformat(),
     "matrix_version": "1.0",
@@ -200,9 +187,7 @@ matrix = {
 MATRIX_JSON.parent.mkdir(parents=True, exist_ok=True)
 MATRIX_JSON.write_text(json.dumps(matrix, indent=2), encoding="utf-8")
 
-# -----------------------------------------------------------------------
-# 6. Emit TRACEABILITY_LATEST.md
-# -----------------------------------------------------------------------
+# --- 6. Emit TRACEABILITY_LATEST.md
 lines = ["# Traceability Matrix", "",
     f"**Generated:** {datetime.now(timezone.utc).strftime('%Y-%m-%d %H:%M:%S UTC')}",
     f"**Total stories:** {len(stories)}",
@@ -237,9 +222,7 @@ if stale_tags:
 TRACE_MD.parent.mkdir(parents=True, exist_ok=True)
 TRACE_MD.write_text("\n".join(lines), encoding="utf-8")
 
-# -----------------------------------------------------------------------
-# 7. Emit OKF bundle (specs/codebase-wiki/)
-# -----------------------------------------------------------------------
+# --- 7. Emit OKF bundle (specs/codebase-wiki/)
 OKF_DIR.mkdir(parents=True, exist_ok=True)
 idx_lines = ["---", "type: Index",
     f"generated_at: {datetime.now(timezone.utc).isoformat()}",
@@ -278,9 +261,7 @@ for s in matrix_stories:
     concept.append("")
     (OKF_DIR / f"{s['id']}.md").write_text("\n".join(concept), encoding="utf-8")
 
-# -----------------------------------------------------------------------
-# 8. Strict mode
-# -----------------------------------------------------------------------
+# --- 8. Strict mode
 if STRICT:
     # Floor assertion — anti-vacuity guard: if story count drops below baseline
     # the matrix is degenerate and --strict must fail open.

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())

package/scripts/sync-skills.sh

@@ -10,7 +10,6 @@
 set -euo pipefail
 source "$(dirname "${BASH_SOURCE[0]}")/lib/python-env.sh"
 
-# ── Parse CLI flags (must happen before source to allow early --help) ─
 OKF_MODE=0
 OPN_TARGET=""
 
@@ -31,7 +30,10 @@ for arg in "$@"; do
   esac
 done
 
-source "$(dirname "${BASH_SOURCE[0]}")/lib/skill-common.sh"
+_LIB_DIR="$(dirname "${BASH_SOURCE[0]}")/lib"
+source "$_LIB_DIR/skill-common.sh"
+source "$_LIB_DIR/sync-render.sh"
+source "$_LIB_DIR/sync-post.sh"
 resolve_repo_root
 
 CURSOR_RULES="$REPO_ROOT/.cursor/rules"
@@ -42,220 +44,14 @@ GEMINI_MANIFEST="$GEMINI_EXT_DIR/gemini-extension.json"
 PI_SKILLS="$REPO_ROOT/.pi/skills"
 PI_PROMPTS="$REPO_ROOT/.pi/prompts"
 PI_PACKAGE_JSON="$REPO_ROOT/.pi/package.json"
-
-mkdir -p "$CURSOR_RULES" "$GEMINI_SKILLS" "$GEMINI_COMMANDS" "$PI_SKILLS" "$PI_PROMPTS"
-
-# Clear old artifacts to ensure a clean sync
-rm -rf "${GEMINI_SKILLS:?}"/*
-rm -rf "${GEMINI_COMMANDS:?}"/*
-rm -rf "${PI_SKILLS:?}"/*
-rm -rf "${PI_PROMPTS:?}"/*
-
-# ── IR: shared intermediate representation ──────────────────────────
-# These globals are set by the main loop per skill and consumed by render functions.
-IR_NAME=""
-IR_MODEL=""
-IR_DESCRIPTION=""
-IR_DESC_ESCAPED=""
-IR_BODY=""
-
-# ── build_body ──────────────────────────────────────────────────────
-# Builds the concatenated content: SKILL.md body + all other *.md files.
-# Args: $1 = path to SKILL.md, $2 = skill directory
-build_body() {
-  local skill_md="$1"
-  local skill_dir="$2"
-  local body
-
-  # Strip frontmatter from SKILL.md (content after second ---)
-  body=$(awk '/^---/{f++; next} f>=2{print}' "$skill_md")
-
-  # Append extra *.md files alphabetically
-  local extra_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
-
-  # Strip disable-model-invocation lines
-  echo "$body" | grep -v 'disable-model-invocation'
-}
-
-# ── Render target: Cursor ───────────────────────────────────────────
-# Writes .cursor/rules/<name>.mdc with YAML frontmatter + body.
-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 target: Gemini Agent Skill ───────────────────────────────
-# Writes .gemini/extensions/bigpowers/skills/<name>/SKILL.md
-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 target: Gemini Slash Command ─────────────────────────────
-# Writes .gemini/extensions/bigpowers/commands/<name>.toml + prompt file
-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 target: pi Agent Skill ───────────────────────────────────
-# Writes .pi/skills/<name>/SKILL.md
-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 target: pi Prompt Template ───────────────────────────────
-# Writes .pi/prompts/<name>.md
-render_pi_prompt() {
-  {
-    echo "---"
-    echo "description: $IR_DESCRIPTION"
-    echo "---"
-    echo ""
-    echo "$IR_BODY"
-  } > "$PI_PROMPTS/$IR_NAME.md"
-}
-
-# ── Render target: OKF Concept (e39s04) ──────────────────────────────
-# Writes specs/skills-wiki/skills/<name>.md with OKF concept frontmatter.
-# Globals used: IR_NAME, IR_MODEL, IR_DESCRIPTION, IR_DESC_ESCAPED, IR_BODY
-# Also reads _PF_EFFORT from the extended parse_frontmatter.
 OKF_WIKI_SKILLS="$REPO_ROOT/specs/skills-wiki/skills"
 OKF_WIKI_DIR="$REPO_ROOT/specs/skills-wiki"
 
-render_okf_concept() {
-  mkdir -p "$OKF_WIKI_SKILLS"
-  local okf_file="$OKF_WIKI_SKILLS/$IR_NAME.md"
-
-  # Determine phase: critical-path skills per the bigpowers core loop
-  local phase="utility"
-  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
-
-  # Build title from name: kebab-case → Title Case
-  local title
-  title=$(echo "$IR_NAME" | sed -E 's/-/ /g; s/\b(.)/\U\1/g')
-
-  # Escape description for YAML double-quoted string
-  local desc_escaped
-  desc_escaped=$(echo "$IR_DESCRIPTION" | sed 's/\\/\\\\/g; s/"/\\"/g')
-
-  # Truncate description to avoid overly long lines (OKF convention)
-  local short_desc="$IR_DESCRIPTION"
-  if [[ ${#short_desc} -gt 200 ]]; then
-    short_desc="${short_desc:0:197}..."
-  fi
-
-  local effort_val="${_PF_EFFORT:-standard}"
-
-  {
-    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"
-}
-
-# ── Parse extended frontmatter for OKF (includes effort) ────────────
-# Wrapper for library parse_frontmatter — sets _PF_* compat vars
-parse_frontmatter() {
-  # Delegate to library which now sets _PF_* vars
-  if command -v skill_common_parse >/dev/null 2>&1 || [ -n "${SKILL_COMMON_LOADED:-}" ]; then
-    source "$(dirname "${BASH_SOURCE[0]}")/lib/skill-common.sh" 2>/dev/null
-  fi
-  # Call library version (defined in skill-common.sh, sets SKILL_NAME and _PF_*)
-  # But since we have the same name, we need the inline version
-  _PF_NAME=$(awk '/^---/{f++} f==1 && /^name:/{print; exit}' "$1" | sed 's/^name:[[:space:]]*//')
-  _PF_MODEL=$(awk '/^---/{f++} f==1 && /^model:/{print; exit}' "$1" | sed 's/^model:[[: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}' "$1" | tr '\n' ' ' | sed 's/[[:space:]]*$//')
-  [[ -z "$_PF_NAME" ]] && return 1
-  return 0
-}
-
-# Extended parse_frontmatter for OKF mode (adds _PF_EFFORT)
-parse_frontmatter_okf() {
-  local file="$1"
-  _PF_EFFORT=""
-
-  if [[ ! -f "$file" ]]; then
-    return 1
-  fi
-
-  if ! 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')
+mkdir -p "$CURSOR_RULES" "$GEMINI_SKILLS" "$GEMINI_COMMANDS" "$PI_SKILLS" "$PI_PROMPTS"
+rm -rf "${GEMINI_SKILLS:?}"/* "${GEMINI_COMMANDS:?}"/* "${PI_SKILLS:?}"/* "${PI_PROMPTS:?}"/*
 
-  [[ -z "$_PF_NAME" ]] && return 1
-  return 0
-}
+IR_NAME="" IR_MODEL="" IR_DESCRIPTION="" IR_DESC_ESCAPED="" IR_BODY=""
 
-# ── Target registry (e37s07) ────────────────────────────────────────
-# Load skill adapters from scripts/targets.yaml — no hardcoded target list.
 TARGETS_FILE="$REPO_ROOT/scripts/targets.yaml"
 SKILL_ADAPTERS=()
 if [[ -f "$TARGETS_FILE" ]] && command -v yq >/dev/null 2>&1; then
@@ -269,8 +65,6 @@ else
 fi
 
 skill_count=0
-
-# ── Main loop: Parse → IR → Render per skill ────────────────────────
 while IFS= read -r skill_dir; do
   skill_md="$skill_dir/SKILL.md"
 
@@ -283,16 +77,12 @@ while IFS= read -r skill_dir; do
   IR_NAME="$_PF_NAME"
   IR_MODEL="$_PF_MODEL"
   IR_DESCRIPTION="$_PF_DESCRIPTION"
-
-  # Escape double quotes and backslashes for safe double-quoted YAML output
   IR_DESC_ESCAPED=$(echo "$IR_DESCRIPTION" | sed 's/\\/\\\\/g; s/\"/\\"/g')
-
   [[ -z "$IR_NAME" ]] && continue
 
   IR_BODY=$(build_body "$skill_md" "$skill_dir")
   SKILL_MD_PATH="$skill_md"
 
-  # Dispatch to each skill adapter from registry (e37s07)
   for adapter_name in "${SKILL_ADAPTERS[@]}"; do
     adapter_script="$REPO_ROOT/scripts/adapters/${adapter_name}.sh"
     # shellcheck source=/dev/null
@@ -300,408 +90,18 @@ while IFS= read -r skill_dir; do
     render_skill
   done
 
-  if [[ "$OKF_MODE" -eq 1 ]]; then
-    render_okf_concept
-  fi
-
+  [[ "$OKF_MODE" -eq 1 ]] && render_okf_concept
   skill_count=$((skill_count + 1))
 done < <(iterate_skills)
 
-# ── Post-loop: manifest, opencode, regeneration, guards, README badge ──
-
-# Assemble final gemini-extension.json
-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"
-
-# Write pi package config: .pi/package.json
-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"
-
-# Write OpenCode configuration: opencode.json
-{
-  echo "{"
-  echo "  \"\$schema\": \"https://opencode.ai/config.json\","
-  echo "  \"instructions\": [\"CLAUDE.md\", \"CONVENTIONS.md\"]"
-  echo "}"
-} > "$REPO_ROOT/opencode.json"
-
-# Sync to bigpowers-opencode repo (if --opencode path is provided)
-if [[ -n "$OPN_TARGET" ]] && [[ -d "$OPN_TARGET" ]]; then
-  echo ""
-  echo "Syncing skills to opencode repo: $OPN_TARGET"
-  OPN_SKILLS="$OPN_TARGET/skills"
-  mkdir -p "$OPN_SKILLS"
-  opencode_count=0
-  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/"
-fi
-
-# Regenerate skills-lock.json catalog
-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
-
-# Regenerate SKILL-INDEX.md from lockfile + frontmatter
-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
-
-# Regenerate lexical skill index for search-skills
-if [[ -x "$REPO_ROOT/scripts/build-skill-index.sh" ]]; then
-  bash "$REPO_ROOT/scripts/build-skill-index.sh" || true
-fi
-
-# Prune orphan cursor rules
-CURSOR_KEEP="context7.mdc"
-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
-
-# Stamp the README skill-count badge
-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"
+opencode_count=0
+[[ -n "$OPN_TARGET" ]] && sync_opencode_copy && opencode_count="${SYNC_OPENCODE_COUNT:-0}"
 
-# ── OKF post-sync pipeline (e39s04) ──────────────────────────────────
 if [[ "$OKF_MODE" -eq 1 ]]; then
   echo ""
   echo "--- OKF skills-wiki post-sync ---"
-
-  # Step 2: Run build-skill-graph.sh to get cross-references in skill-graph.json
-  GRAPH_JSON="$REPO_ROOT/specs/skill-graph.json"
-  if [[ -x "$REPO_ROOT/scripts/build-skill-graph.sh" ]]; then
-    echo "Running build-skill-graph.sh for cross-references..."
-    bash "$REPO_ROOT/scripts/build-skill-graph.sh" --json || {
-      echo "sync-skills: WARNING — build-skill-graph.sh --json failed; cross-references will be empty" >&2
-    }
-  else
-    echo "sync-skills: WARNING — build-skill-graph.sh not found; skipping cross-references" >&2
-  fi
-
-  # Step 2b: Add cross-references from skill-graph.json edges into OKF concepts
-  if [[ -f "$GRAPH_JSON" ]]; then
-    echo "Adding cross-references from skill-graph.json..."
-    $PYTHON - "$GRAPH_JSON" "$OKF_WIKI_SKILLS" <<'PYEOF'
-import json, sys, re
-from pathlib import Path
-
-graph_json = Path(sys.argv[1])
-wiki_skills = Path(sys.argv[2])
-
-# Load graph edges
-with open(graph_json) as f:
-    graph = json.load(f)
-
-edges = graph.get("edges", [])
-nodes = {n["name"] for n in graph.get("nodes", [])}
-
-# Build adjacency: skill_name -> list of {concept, type} refs
-refs = {}
-for e in edges:
-    src, tgt, rel = e["from"], e["to"], e.get("relationType", "references")
-    # Only include edges where both ends are known skills
-    if src in nodes and tgt in nodes:
-        refs.setdefault(src, []).append({"concept": tgt, "type": rel})
-
-# Also detect intra-description references: scan description for skill names
-skill_names = set()
-for f in wiki_skills.glob("*.md"):
-    skill_names.add(f.stem)
-
-# Update each concept file with references
-count_updated = 0
-for f in wiki_skills.glob("*.md"):
-    name = f.stem
-    content = f.read_text()
-
-    # Collect references for this skill
-    concept_refs = refs.get(name, [])
-
-    # Also scan description for mentions of other skill names
-    desc_match = re.search(r'description:\s*"(.*?)"', content, re.DOTALL)
-    if desc_match:
-        desc = desc_match.group(1)
-        for sn in skill_names:
-            if sn != name and sn in desc and not any(r["concept"] == sn for r in concept_refs):
-                concept_refs.append({"concept": sn, "type": "references"})
-
-    # Deduplicate
-    seen = set()
-    unique_refs = []
-    for r in concept_refs:
-        key = (r["concept"], r["type"])
-        if key not in seen:
-            seen.add(key)
-            unique_refs.append(r)
-
-    # Build YAML references block
-    if unique_refs:
-        ref_lines = []
-        for r in unique_refs:
-            ref_lines.append(f'  - concept: {r["concept"]}')
-            ref_lines.append(f'    type: {r["type"]}')
-        ref_block = "\n".join(ref_lines)
-        content = re.sub(r'references:\s*\[\]', f'references:\n{ref_block}', content)
-        count_updated += 1
-    else:
-        # No edges and no description mentions → self-reference as fallback
-        content = re.sub(
-            r'references:\s*\[\]',
-            f'references:\n  - concept: skills-wiki\n    type: belongs_to',
-            content
-        )
-        count_updated += 1
-
-    f.write_text(content)
-
-print(f"  concepts with cross-references: {count_updated}", file=sys.stderr)
-PYEOF
-  else
-    echo "sync-skills: WARNING — $GRAPH_JSON not found; adding fallback references" >&2
-    # Add fallback references to all concepts
-    for f in "$OKF_WIKI_SKILLS"/*.md; do
-      [[ -f "$f" ]] || continue
-      if command -v $PYTHON &>/dev/null; then
-        $PYTHON -c "
-import re, sys
-content = open('$f').read()
-content = re.sub(r'references:\s*\[\]', 'references:\n  - concept: skills-wiki\n    type: belongs_to', content)
-open('$f', 'w').write(content)
-"
-      fi
-    done
-  fi
-
-  # Step 3: Generate specs/skills-wiki/index.md with progressive disclosure
-  echo "Generating index.md..."
-  OKF_INDEX="$OKF_WIKI_DIR/index.md"
-  $PYTHON - "$OKF_WIKI_SKILLS" "$OKF_WIKI_DIR" "$OKF_INDEX" <<'PYEOF'
-import json, sys, re
-from pathlib import Path
-from collections import defaultdict
-
-wiki_skills = Path(sys.argv[1])
-wiki_dir = Path(sys.argv[2])
-index_path = Path(sys.argv[3])
-
-# Collect all concepts
-concepts = []
-for f in sorted(wiki_skills.glob("*.md")):
-    content = f.read_text()
-    fm_match = re.search(r'^---\n(.*?)\n---', content, re.DOTALL)
-    if not fm_match:
-        continue
-    fm_text = fm_match.group(1)
-    # Simple YAML extraction
-    name = ""
-    title = ""
-    phase = "utility"
-    model = ""
-    effort = ""
-    description = ""
-    for line in fm_text.split('\n'):
-        line = line.strip()
-        if line.startswith('name:'):
-            name = line.split(':', 1)[1].strip()
-        elif line.startswith('title:'):
-            title = line.split(':', 1)[1].strip().strip('"')
-        elif line.startswith('phase:'):
-            phase = line.split(':', 1)[1].strip()
-        elif line.startswith('model:'):
-            model = line.split(':', 1)[1].strip()
-        elif line.startswith('effort:'):
-            effort = line.split(':', 1)[1].strip()
-        elif line.startswith('description:'):
-            description = line.split(':', 1)[1].strip().strip('"')
-    if not name:
-        continue
-    concepts.append({
-        "name": name,
-        "title": title or name.replace('-', ' ').title(),
-        "phase": phase,
-        "model": model,
-        "effort": effort,
-        "description": description[:120] + "..." if len(description) > 120 else description,
-    })
-
-# Group by phase
-phases = defaultdict(list)
-for c in concepts:
-    phases[c["phase"]].append(c)
-
-# Count
-total = len(concepts)
-cp_count = len(phases.get("critical-path", []))
-util_count = len(phases.get("utility", []))
-
-# Generate index.md
-with open(index_path, "w") as out:
-    out.write(f"""---
-okf_kind: concept
-type: Index
-id: skills-wiki
-title: "BigPowers Skills Wiki"
-category: skills
-description: "Progressive-disclosure index of {total} bigpowers skills ({cp_count} critical-path, {util_count} utility) — auto-generated by sync-skills.sh --okf (e39s04)."
-references:
-  - concept: bigpowers
-    type: belongs_to
----
-
-# BigPowers Skills Wiki
-
-**{total} skills** ({cp_count} critical-path, {util_count} utility)
-
-> Auto-generated by sync-skills.sh --okf (e39s04).
-> Source of truth: skills/*/SKILL.md files.
-
-## Critical-Path Skills ({cp_count})
-
-These skills form the bigpowers core development loop — used on every feature.
-
-| Skill | Model | Effort | Description |
-|-------|-------|--------|-------------|
-""")
-
-    for c in phases.get("critical-path", []):
-        out.write(f"| [{c['title']}](skills/{c['name']}.md) | {c['model']} | {c['effort']} | {c['description']} |\n")
-
-    out.write(f"""
-## Utility Skills ({util_count})
-
-Supporting skills for specialised workflows.
-
-| Skill | Model | Effort | Description |
-|-------|-------|--------|-------------|
-""")
-
-    for c in phases.get("utility", []):
-        out.write(f"| [{c['title']}](skills/{c['name']}.md) | {c['model']} | {c['effort']} | {c['description']} |\n")
-
-    out.write(f"""
-## Quick Reference
-
-- **Total skills:** {total}
-- **Critical-path:** {cp_count}
-- **Utility:** {util_count}
-- **Format:** OKF concept bundles (okf_kind: concept)
-- **Validation:** `bash scripts/validate-okf.sh --dir specs/skills-wiki/skills`
-""")
-
-print(f"  index.md written: {total} skills indexed", file=sys.stderr)
-PYEOF
-
-  # Step 4: Validate OKF conformance via validate-okf.sh
-  echo ""
-  echo "Validating OKF conformance..."
-  VALIDATE_SCRIPT="$REPO_ROOT/scripts/validate-okf.sh"
-  if [[ -x "$VALIDATE_SCRIPT" ]]; then
-    if bash "$VALIDATE_SCRIPT" --dir "$OKF_WIKI_SKILLS" 2>&1; then
-      echo "sync-skills: OKF validation PASSED"
-    else
-      OKF_EXIT=$?
-      echo "sync-skills: OKF validation returned exit code $OKF_EXIT (non-zero — check output above)" >&2
-      # Don't hard-fail on validation warnings; the bundle is still generated
-    fi
-  else
-    echo "sync-skills: WARNING — validate-okf.sh not found; skipping validation" >&2
-  fi
-
-  OKF_CONCEPT_COUNT=$(find "$OKF_WIKI_SKILLS" -name "*.md" 2>/dev/null | wc -l | tr -d ' ')
-  echo ""
-  echo "sync-skills (--okf): $OKF_CONCEPT_COUNT OKF concepts generated"
-  echo "  → specs/skills-wiki/skills/ ($OKF_CONCEPT_COUNT .md files)"
-  echo "  → specs/skills-wiki/index.md (progressive-disclosure index)"
-fi
-
-# Regression guard (BUG-2026-06-02T164500)
-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 [[ -z "$ext_ver" || -z "$pkg_ver" ]]; then
-    : # skip version compare when either field is missing
-  elif [[ "$ext_ver" != "$pkg_ver" ]]; then
-    echo "sync-skills: FAIL — gemini-extension.json version ($ext_ver) != package.json ($pkg_ver)" >&2
-    exit 1
-  fi
-fi
-
-# Regression guard (BUG-2026-06-18T100000): validate generated YAML frontmatter
-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
-
-# Regression guard (BUG-2026-07-02T103911): no bash 4+ features
-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
+  bash "$REPO_ROOT/scripts/okf-post-sync.sh"
 fi
 
-# Regenerate derived reference tables
-if [[ -d "$REPO_ROOT/.git" ]]; then
-  bash "$REPO_ROOT/scripts/generate-reference-tables.sh"
-fi
-
-# ── OKF wiki generation (e45s01) ──────────────────────────────────────
-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_run "$skill_count" "$opencode_count"
 exit 0