bigpowers 2.75.2 → 2.76.0

package/.pi/package.json

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

package/CHANGELOG.md

@@ -1,3 +1,16 @@
+# [2.76.0](https://github.com/danielvm-git/bigpowers/compare/v2.75.2...v2.76.0) (2026-07-07)
+
+
+### Bug Fixes
+
+* **ci:** add OKF type fields and gate wiki publish on WIKI_PAT ([9628122](https://github.com/danielvm-git/bigpowers/commit/96281227e91ebed19300daed8dd05d51d6021c9e))
+* **ci:** skip estimated commit_range check and wiki publish without PAT ([bf079ad](https://github.com/danielvm-git/bigpowers/commit/bf079ad384c4363980fe30383406d37629718b89))
+
+
+### Features
+
+* **e37:** Reach — Close release: AGENTS.md spine, targets.yaml registry, OSS waves A-E; fix 6 compliance bugs ([5a7f407](https://github.com/danielvm-git/bigpowers/commit/5a7f407008818cec518969a2b46e5ae28ee130bb))
+
 ## [2.75.2](https://github.com/danielvm-git/bigpowers/compare/v2.75.1...v2.75.2) (2026-07-07)
 
 

package/kernel/src/publish-to-wiki.sh

@@ -83,8 +83,13 @@ push_to_wiki() {
   local work_dir="${WIKI_WORK_DIR:-}"
 
   if [[ -z "$wiki_repo" ]]; then
-    echo "publish-to-wiki: WIKI_REPO_URL is not set — cannot push" >&2
-    return 1
+    echo "publish-to-wiki: WIKI_REPO_URL is not set — skipping push" >&2
+    return 0
+  fi
+
+  local clone_url="$wiki_repo"
+  if [[ -n "${WIKI_PAT:-}" && "$wiki_repo" == https://* ]]; then
+    clone_url="${wiki_repo/https:\/\//https://x-access-token:${WIKI_PAT}@}"
   fi
 
   if [[ -z "$work_dir" ]]; then
@@ -95,7 +100,7 @@ push_to_wiki() {
   if [[ -d "$work_dir/.git" ]]; then
     git -C "$work_dir" pull --rebase origin master 2>/dev/null || git -C "$work_dir" pull --rebase origin main
   else
-    git clone "$wiki_repo" "$work_dir"
+    git clone "$clone_url" "$work_dir"
   fi
 
   rsync -a --delete "$staged_root/" "$work_dir/"
@@ -137,4 +142,9 @@ if [[ "$DRY_RUN" -eq 1 ]]; then
   exit 0
 fi
 
+if [[ -z "${WIKI_PAT:-}" ]]; then
+  echo "publish-to-wiki: WIKI_PAT not set — skipping wiki push"
+  exit 0
+fi
+
 push_to_wiki "$STAGING"

package/package.json

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

package/scripts/audit-compliance.sh

@@ -1,9 +1,8 @@
 #!/usr/bin/env bash
 # audit-compliance.sh — Agentic Gherkin Compliance Harness (LLM-Judge Upgrade)
 
-_LIB="$(dirname "${BASH_SOURCE[0]}")/lib"
-source "$_LIB/audit-compliance-runner.sh"
-source "$_LIB/audit-compliance-report.sh"
+source "$(dirname "${BASH_SOURCE[0]}")/lib/audit-compliance-runner.sh"
+source "$(dirname "${BASH_SOURCE[0]}")/lib/audit-compliance-report.sh"
 
 audit_show_help() {
   cat <<EOF

package/scripts/build-receipts.sh

@@ -6,7 +6,7 @@ source "$(dirname "${BASH_SOURCE[0]}")/lib/python-env.sh"
 ROOT="$(git rev-parse --show-toplevel 2>/dev/null)" || { echo "build-receipts: not inside a git repo" >&2; exit 1; }
 OUTFILE="$ROOT/specs/receipts.json"
 TIMESTAMP="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
-emit_json() {
+receipts_emit_json() {
   $PYTHON -c "
 import json, sys, os, subprocess, glob as gb
 sections = {}
@@ -103,6 +103,6 @@ for key, sec in sections.items(): print(f'  {key}: source={sec.get(\"source\",\"
 "
 }
 echo "build-receipts: aggregating quality evidence..."
-emit_json
+receipts_emit_json
 echo "build-receipts: done — $(date -u +%H:%M:%SZ)"
 exit 0

package/scripts/build-skill-graph.sh

@@ -12,7 +12,7 @@ GRAPH_JSONL="$REPO_ROOT/bigpowers-mcp/graph.jsonl"
 SKILL_GRAPH_JSON="$REPO_ROOT/specs/skill-graph.json"
 SKILLS_WIKI="$REPO_ROOT/specs/skills-wiki/skills"
 
-show_help() {
+skill_graph_show_help() {
   cat <<EOF
 Usage: $(basename "$0") [OPTION]
 

package/scripts/check-spec-drift.sh

@@ -10,7 +10,7 @@ REPO_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
 TRACE_MATRIX="$REPO_ROOT/specs/traceability-matrix.json"
 DRIFT_REPORT="$REPO_ROOT/specs/drift-report.json"
 
-show_help() {
+drift_show_help() {
   cat <<EOF
 Usage: $(basename "$0") [OPTION]
 
@@ -23,7 +23,7 @@ EOF
 }
 
 if [ "$#" -eq 1 ] && [ "$1" = "--help" ]; then
-  show_help
+  drift_show_help
   exit 0
 fi
 

package/scripts/check-spec-version-gap.sh

@@ -5,7 +5,7 @@ source "$(dirname "${BASH_SOURCE[0]}")/lib/python-env.sh"
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 BP_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
 
-usage() {
+gap_usage() {
   cat <<'EOF'
 Usage: check-spec-version-gap.sh [--help] [--project <dir>] [--json]
 Exit codes: 0=no gap, 1=gap, 2=no specs, 3=blocked, 4=error
@@ -18,7 +18,7 @@ JSON_STDOUT=false
 SKIP_BLOCK=false
 while [[ $# -gt 0 ]]; do
   case "$1" in
-    --help|-h) usage ;;
+    --help|-h) gap_usage ;;
     --project) PROJECT_DIR="${2:?}"; shift 2 ;;
     --json) JSON_STDOUT=true; shift ;;
     --skip-block) SKIP_BLOCK=true; shift ;;
@@ -29,7 +29,7 @@ done
 PROJECT_DIR="$(cd "$PROJECT_DIR" 2>/dev/null && pwd)" || { echo "bad dir: $PROJECT_DIR" >&2; exit 4; }
 SPECS="$PROJECT_DIR/specs"
 
-emit_json() {
+gap_emit_json() {
   if $JSON_STDOUT; then echo "$1"; else echo "$1" >&2; fi
 }
 
@@ -37,7 +37,7 @@ get_installed_version() {
   $PYTHON -c "import json; d=json.load(open('$BP_ROOT/package.json')); print(d.get('version','unknown'))" 2>/dev/null || echo "unknown"
 }
 
-yaml_get() {
+gap_yaml_get() {
   [[ ! -f "$1" ]] && { echo ""; return; }
   $PYTHON -c "
 import sys, yaml
@@ -116,29 +116,29 @@ check_active_work() {
   branch=$(git -C "$PROJECT_DIR" branch --show-current 2>/dev/null || echo "")
   if on_feature_branch "$branch"; then echo "true"; return; fi
   if has_dirty_specs; then echo "true"; return; fi
-  af=$(yaml_get "$SPECS/state.yaml" "active_flow")
+  af=$(gap_yaml_get "$SPECS/state.yaml" "active_flow")
   if is_blocking_active_flow "$af"; then echo "true"; return; fi
   echo "false"
 }
 
 # Main
-[[ ! -d "$SPECS" ]] && { emit_json '{"gap":false,"reason":"NO_SPECS"}'; exit 2; }
+[[ ! -d "$SPECS" ]] && { gap_emit_json '{"gap":false,"reason":"NO_SPECS"}'; exit 2; }
 IV=$(get_installed_version)
 if [ "$SKIP_BLOCK" != "true" ] && [[ "$(check_active_work)" == "true" ]]; then
-  emit_json '{"gap":true,"blocked":true,"reason":"ACTIVE_WORK","installed_version":"'"$IV"'"}'
+  gap_emit_json '{"gap":true,"blocked":true,"reason":"ACTIVE_WORK","installed_version":"'"$IV"'"}'
   exit 3
 fi
 
-SV=$(yaml_get "$SPECS/state.yaml" "bigpowers_version")
+SV=$(gap_yaml_get "$SPECS/state.yaml" "bigpowers_version")
 
 if yaml_value_set "$SV"; then
   if [[ "$SV" == "$IV" ]]; then
-    emit_json '{"gap":false,"stamp":true,"detected_version":"'"$SV"'","installed_version":"'"$IV"'","detection_method":"stamp","confidence":"high"}'
+    gap_emit_json '{"gap":false,"stamp":true,"detected_version":"'"$SV"'","installed_version":"'"$IV"'","detection_method":"stamp","confidence":"high"}'
     exit 0
   fi
   APP=$(find_migrations "$SV")
   CNT=$(echo "$APP" | $PYTHON -c "import json,sys; print(len(json.load(sys.stdin)))" 2>/dev/null || echo 0)
-  emit_json "$($PYTHON -c "import json; a=json.loads('''$APP'''); print(json.dumps({'gap':True,'stamp':True,'detected_version':'$SV','detection_method':'stamp','installed_version':'$IV','applicable_migrations':len(a),'migration_ids':[m['id'] for m in a],'confidence':'high','active_work_blocked':False}))")"
+  gap_emit_json "$($PYTHON -c "import json; a=json.loads('''$APP'''); print(json.dumps({'gap':True,'stamp':True,'detected_version':'$SV','detection_method':'stamp','installed_version':'$IV','applicable_migrations':len(a),'migration_ids':[m['id'] for m in a],'confidence':'high','active_work_blocked':False}))")"
   exit 1
 fi
 
@@ -150,7 +150,7 @@ for f in release-plan.yaml execution-status.yaml product/SCOPE_LATEST.yaml metri
   [[ -f "$SPECS/$f" ]] && { MARKERS+=("$f"); [[ -z "$DV" ]] && DV="2.0.0"; }
 done
 if [[ -f "$SPECS/state.yaml" ]]; then
-  ec=$(yaml_get "$SPECS/state.yaml" "epic_cycle.current_step")
+  ec=$(gap_yaml_get "$SPECS/state.yaml" "epic_cycle.current_step")
   if yaml_value_set "$ec"; then
     MARKERS+=("epic_cycle"); [[ "$DV" == "2.0.0" ]] && DV="2.20.0"
   fi
@@ -161,12 +161,12 @@ fi
 [[ -z "$DV" ]] && { DV="unknown"; CONF="low"; }
 
 if [[ "$DV" != "unknown" ]] && ! version_lt "$DV" "$IV"; then
-  [[ "$DV" == "$IV" ]] && { emit_json '{"gap":false,"stamp":false,"detected_version":"'"$DV"'","installed_version":"'"$IV"'","detection_method":"fingerprint","confidence":"'"$CONF"'"}'; exit 0; }
+  [[ "$DV" == "$IV" ]] && { gap_emit_json '{"gap":false,"stamp":false,"detected_version":"'"$DV"'","installed_version":"'"$IV"'","detection_method":"fingerprint","confidence":"'"$CONF"'"}'; exit 0; }
 fi
 
 APP=$(find_migrations "$DV")
 CNT=$(echo "$APP" | $PYTHON -c "import json,sys; print(len(json.load(sys.stdin)))" 2>/dev/null || echo 0)
 MJ=$(printf '%s\n' "${MARKERS[@]}" | $PYTHON -c "import json,sys; print(json.dumps([l.strip() for l in sys.stdin if l.strip()]))" 2>/dev/null || echo "[]")
 
-emit_json "$($PYTHON -c "import json; a=json.loads('''$APP'''); m=json.loads('''$MJ'''); print(json.dumps({'gap':True,'stamp':False,'detected_version':'$DV','detection_method':'fingerprint','installed_version':'$IV','applicable_migrations':len(a),'migration_ids':[x['id'] for x in a],'confidence':'$CONF','active_work_blocked':False,'matched_markers':m}))")"
+gap_emit_json "$($PYTHON -c "import json; a=json.loads('''$APP'''); m=json.loads('''$MJ'''); print(json.dumps({'gap':True,'stamp':False,'detected_version':'$DV','detection_method':'fingerprint','installed_version':'$IV','applicable_migrations':len(a),'migration_ids':[x['id'] for x in a],'confidence':'$CONF','active_work_blocked':False,'matched_markers':m}))")"
 exit 1

package/scripts/compile-rule-matrix.sh

@@ -10,7 +10,7 @@ CONVENTIONS="$REPO_ROOT/CONVENTIONS.md"
 OUTPUT="$REPO_ROOT/specs/rule-matrix.json"
 MATRIX_VERSION="1.0.0"
 
-show_help() {
+matrix_show_help() {
   cat <<EOF
 Usage: $(basename "$0") [OPTION]
 
@@ -26,7 +26,7 @@ EOF
 STDOUT_ONLY=0
 if [ "$#" -eq 1 ]; then
   case "$1" in
-    --help) show_help; exit 0 ;;
+    --help) matrix_show_help; exit 0 ;;
     --stdout) STDOUT_ONLY=1 ;;
     *) echo "[ERROR] Unknown option: $1" >&2; exit 1 ;;
   esac

package/scripts/decompose-conventions.sh

@@ -11,7 +11,7 @@ CONVENTIONS_WIKI="$REPO_ROOT/specs/conventions-wiki"
 CONVENTIONS_INDEX="$CONVENTIONS_WIKI/index.md"
 SKILL_GRAPH="$REPO_ROOT/specs/skill-graph.json"
 
-show_help() {
+decompose_show_help() {
   cat <<EOF
 Usage: $(basename "$0") [OPTION]
 
@@ -24,7 +24,7 @@ EOF
 }
 
 if [ "$#" -eq 1 ] && [ "$1" = "--help" ]; then
-  show_help
+  decompose_show_help
   exit 0
 fi
 

package/scripts/generate-adr-wiki.sh

@@ -17,7 +17,7 @@ fi
 
 count=0
 
-assign_tier() {
+adr_wiki_assign_tier() {
   local adr_id="$1"
   case "$adr_id" in
     ADR-0001|ADR-0002|ADR-0003|0001-*|0002-*|0003-*) echo "core" ;;
@@ -55,7 +55,7 @@ if len(parts) >= 3:
   fi
   [ -z "$title" ] && title="$adr_name"
 
-  tier=$(assign_tier "$adr_name")
+  tier=$(adr_wiki_assign_tier "$adr_name")
 
   bundle="$WIKI/${adr_name}.okf.md"
 

package/scripts/generate-agent-guide.sh

@@ -9,7 +9,7 @@ REPO_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
 CLAUDE_MD="$REPO_ROOT/CLAUDE.md"
 AGENT_GUIDE="$REPO_ROOT/specs/agent-guide"
 
-show_help() {
+agent_guide_show_help() {
   cat <<EOF
 Usage: $(basename "$0") [OPTION]
 
@@ -22,7 +22,7 @@ EOF
 }
 
 if [ "$#" -eq 1 ] && [ "$1" = "--help" ]; then
-  show_help
+  agent_guide_show_help
   exit 0
 fi
 

package/scripts/generate-epics-wiki.sh

@@ -16,7 +16,7 @@ extract() {
 
 count=0
 
-assign_tier() {
+epics_wiki_assign_tier() {
   local epic_id="$1"
   case "$epic_id" in
     e28|e38|e40|e41|e44|e45|e46) echo "core" ;;
@@ -43,7 +43,7 @@ for epic_yaml in "$ROOT"/specs/epics/*/epic.yaml "$ROOT"/specs/epics/archive/*/e
 
   [[ -z "$epic_id" ]] && continue
 
-  tier=$(assign_tier "$epic_id")
+  tier=$(epics_wiki_assign_tier "$epic_id")
 
   # Build references array from story list
   story_count=$(grep -c '^\s*- id:' "$epic_yaml" 2>/dev/null || true)

package/scripts/hooks/token-mgmt-pre-tool-use.sh

@@ -7,7 +7,7 @@ READ_MAX_BYTES=102400   # 100KB
 GREP_MAX_MATCHES=200
 BASH_WARN_PATTERNS='^(npm test|pnpm test|yarn test|cargo test|go test|jest|vitest|pytest|rake test|rspec|git log|git diff|docker logs|kubectl logs|find |rg |grep )'
 
-deny() {
+token_mgmt_deny() {
   echo "TOKEN-MGMT BLOCK: $1" >&2
   echo "Use sqz_read_file / sqz_grep / rtk / bts compress per CLAUDE.md § Token Management." >&2
   exit 2
@@ -23,16 +23,16 @@ case "$TOOL" in
     [[ -n "$PATH_ARG" && -f "$PATH_ARG" ]] || exit 0
     SIZE="$(wc -c < "$PATH_ARG" | tr -d ' ')"
     if (( SIZE > READ_MAX_BYTES )); then
-      deny "Read $PATH_ARG is ${SIZE} bytes (max ${READ_MAX_BYTES}). Use sqz_read_file or bts compress."
+      token_mgmt_deny "Read $PATH_ARG is ${SIZE} bytes (max ${READ_MAX_BYTES}). Use sqz_read_file or bts compress."
     fi
     ;;
   Grep|grep)
     LIMIT="$(echo "$TOOL_INPUT" | jq -r '.head_limit // .max_matches // empty')"
     if [[ -z "$LIMIT" || "$LIMIT" == "null" ]]; then
-      deny "Grep without head_limit (max ${GREP_MAX_MATCHES}). Set head_limit<=${GREP_MAX_MATCHES} or use sqz_grep."
+      token_mgmt_deny "Grep without head_limit (max ${GREP_MAX_MATCHES}). Set head_limit<=${GREP_MAX_MATCHES} or use sqz_grep."
     fi
     if [[ "$LIMIT" =~ ^[0-9]+$ ]] && (( LIMIT > GREP_MAX_MATCHES )); then
-      deny "Grep head_limit=${LIMIT} exceeds ${GREP_MAX_MATCHES}. Lower limit or use sqz_grep."
+      token_mgmt_deny "Grep head_limit=${LIMIT} exceeds ${GREP_MAX_MATCHES}. Lower limit or use sqz_grep."
     fi
     ;;
   Bash|bash|Shell|shell)
@@ -42,7 +42,7 @@ case "$TOOL" in
       exit 0
     fi
     if echo "$CMD" | grep -qE "$BASH_WARN_PATTERNS"; then
-      deny "Bash may exceed 500 lines of output. Prefix with rtk or pipe through sqz compress."
+      token_mgmt_deny "Bash may exceed 500 lines of output. Prefix with rtk or pipe through sqz compress."
     fi
     ;;
   *)

package/scripts/land-branch.sh

@@ -13,7 +13,7 @@ usage_land() {
   exit 1
 }
 
-deny() {
+land_branch_deny() {
   echo "ERROR: $1" >&2
   exit 1
 }
@@ -34,16 +34,16 @@ COMMIT_MSG="${ARGS[1]:-}"
 [ -n "$FEATURE_BRANCH" ] && [ -n "$COMMIT_MSG" ] || usage_land
 
 if [[ ! "$COMMIT_MSG" =~ $CONVENTIONAL_REGEX ]]; then
-  deny "Commit message must follow Conventional Commits: <type>(<scope>): <subject>"
+  land_branch_deny "Commit message must follow Conventional Commits: <type>(<scope>): <subject>"
 fi
 
 if [ ${#COMMIT_MSG} -gt 72 ]; then
-  deny "Commit subject line must be 72 characters or less"
+  land_branch_deny "Commit subject line must be 72 characters or less"
 fi
 
 # Primary worktree only (.git is a directory, not a gitdir pointer file)
 if [ -f .git ]; then
-  deny "Run from the primary repository root, not a linked worktree (cd to main repo first)"
+  land_branch_deny "Run from the primary repository root, not a linked worktree (cd to main repo first)"
 fi
 
 detect_default_branch() {
@@ -58,7 +58,7 @@ detect_default_branch() {
   elif git show-ref --verify --quiet refs/heads/master; then
     echo "master"
   else
-    deny "Could not detect default branch (main/master)"
+    land_branch_deny "Could not detect default branch (main/master)"
   fi
 }
 
@@ -69,12 +69,12 @@ echo "==> Land branch: $FEATURE_BRANCH -> $DEFAULT_BRANCH"
 echo "    Repo root: $REPO_ROOT"
 
 if ! git show-ref --verify --quiet "refs/heads/$FEATURE_BRANCH"; then
-  deny "Feature branch '$FEATURE_BRANCH' does not exist"
+  land_branch_deny "Feature branch '$FEATURE_BRANCH' does not exist"
 fi
 
 for protected in main master; do
   if [ "$FEATURE_BRANCH" = "$protected" ]; then
-    deny "Cannot land protected branch '$FEATURE_BRANCH'"
+    land_branch_deny "Cannot land protected branch '$FEATURE_BRANCH'"
   fi
 done
 
@@ -115,15 +115,15 @@ fi
 echo "==> Updating $DEFAULT_BRANCH"
 git checkout "$DEFAULT_BRANCH"
 if ! git diff-index --quiet HEAD -- 2>/dev/null; then
-  deny "Working tree on $DEFAULT_BRANCH is not clean. Stash or commit first."
+  land_branch_deny "Working tree on $DEFAULT_BRANCH is not clean. Stash or commit first."
 fi
 
 if git remote get-url origin >/dev/null 2>&1; then
-  git pull --ff-only origin "$DEFAULT_BRANCH" || deny "git pull --ff-only failed; resolve before landing"
+  git pull --ff-only origin "$DEFAULT_BRANCH" || land_branch_deny "git pull --ff-only failed; resolve before landing"
 fi
 
 if ! git merge-base --is-ancestor "$DEFAULT_BRANCH" "$FEATURE_BRANCH" 2>/dev/null; then
-  deny "Feature branch '$FEATURE_BRANCH' is not based on current $DEFAULT_BRANCH (rebase or recreate branch)"
+  land_branch_deny "Feature branch '$FEATURE_BRANCH' is not based on current $DEFAULT_BRANCH (rebase or recreate branch)"
 fi
 
 export GIT_BIGPOWERS_LAND=1
@@ -131,7 +131,7 @@ export GIT_BIGPOWERS_LAND=1
 echo "==> Squash merge $FEATURE_BRANCH"
 git merge --squash "$FEATURE_BRANCH"
 if git diff-index --quiet HEAD -- 2>/dev/null; then
-  deny "Squash merge produced no changes (already merged?)"
+  land_branch_deny "Squash merge produced no changes (already merged?)"
 fi
 
 git commit -m "$COMMIT_MSG"

package/scripts/lib/audit-compliance-report.sh

@@ -26,6 +26,7 @@ audit_write_okf_report() {
 ---
 okf_kind: verification-report
 okf_version: "0.1"
+type: VerificationReport
 score: ${SCORE}
 gate_status: "${GATE}"
 threshold: 94

package/scripts/lib/emit-okf-metrics.sh

@@ -31,6 +31,7 @@ emit_okf_metrics() {
     printf -- '---\n'
     printf -- 'okf_kind: story-metrics\n'
     printf -- 'okf_version: "0.1"\n'
+    printf -- 'type: StoryMetrics\n'
     printf -- 'id: %s\n' "$story"
     printf -- 'epic: %s\n' "${story%%s*}"
     printf -- 'bcps: %s\n' "$bcps"

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

@@ -80,6 +80,7 @@ YAML_EOF
 ---
 okf_kind: verification-report
 okf_version: "0.1"
+type: VerificationReport
 score: ${PASS_RATE}
 gate_status: "${GATE_STATUS}"
 threshold: ${THRESHOLD}

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

@@ -32,7 +32,11 @@ golden_suite_main() {
     esac
   done
 
-  if $AGENT_MODE && ! command -v gh-aw &>/dev/null && ! command -v gh &>/dev/null; then
+  golden_agent_cli_available() {
+    $AGENT_MODE && ! command -v gh-aw &>/dev/null && ! command -v gh &>/dev/null
+  }
+
+  if golden_agent_cli_available; then
     echo -e "${GOLDEN_YELLOW}WARNING: gh-aw not installed — agent gate skipped${GOLDEN_NC}" >&2
     AGENT_MODE=false
   fi

package/scripts/lib/migrate-version-transforms.sh

@@ -2,7 +2,6 @@
 # story: e44s03
 if [ -n "${MIGRATE_VERSION_TRANSFORMS_LOADED:-}" ]; then return 0; fi
 MIGRATE_VERSION_TRANSFORMS_LOADED=1
-yaml_get() { migrate_yaml_get "$@"; }
 apply_transform() {
   local mig_id="$1" action="$2" tjson="$3"
 
@@ -107,7 +106,7 @@ with open(tgt, 'w') as f:
       val="$(echo "$tjson" | $PYTHON -c "import json,sys; print(json.load(sys.stdin).get('value',''))")"
       if_missing="$(echo "$tjson" | $PYTHON -c "import json,sys; print(json.load(sys.stdin).get('if_missing','false'))" 2>/dev/null)" || if_missing="false"
       if [ "$if_missing" = "true" ] || [ "$if_missing" = "True" ]; then
-        if yaml_get "$REPO_ROOT/$file" "$key" >/dev/null 2>&1; then
+        if migrate_yaml_get "$REPO_ROOT/$file" "$key" >/dev/null 2>&1; then
           log_skip "$action: $file $key already set (if_missing=true) — idempotent"
           SKIPPED+=("$action:$key")
           return
@@ -122,7 +121,7 @@ with open(tgt, 'w') as f:
       file="$(echo "$tjson" | $PYTHON -c "import json,sys; print(json.load(sys.stdin).get('file',''))")"
       old_key="$(echo "$tjson" | $PYTHON -c "import json,sys; print(json.load(sys.stdin).get('old_key',''))")"
       new_key="$(echo "$tjson" | $PYTHON -c "import json,sys; print(json.load(sys.stdin).get('new_key',''))")"
-      old_val="$(yaml_get "$REPO_ROOT/$file" "$old_key" 2>/dev/null)" || true
+      old_val="$(migrate_yaml_get "$REPO_ROOT/$file" "$old_key" 2>/dev/null)" || true
       if [ -z "${old_val:-}" ]; then
         log_skip "$action: key '$old_key' not found in $file"
         SKIPPED+=("$action:$old_key"); return
@@ -148,7 +147,7 @@ with open('$REPO_ROOT/$file', 'w') as f:
       local file key
       file="$(echo "$tjson" | $PYTHON -c "import json,sys; print(json.load(sys.stdin).get('file',''))")"
       key="$(echo "$tjson" | $PYTHON -c "import json,sys; d=json.load(sys.stdin); print(d.get('path') or d.get('key',''))")"
-      if ! yaml_get "$REPO_ROOT/$file" "$key" >/dev/null 2>&1; then
+      if ! migrate_yaml_get "$REPO_ROOT/$file" "$key" >/dev/null 2>&1; then
         log_skip "$action: key '$key' not found in $file — idempotent"
         SKIPPED+=("$action:$key"); return
       fi

package/scripts/lib/record-cycle-time-lib.sh

@@ -0,0 +1,31 @@
+#!/usr/bin/env bash
+# record-cycle-time-lib.sh — shared helpers for record-cycle-time.sh
+
+record_cycle_die() { echo "record-cycle-time: $*" >&2; exit 1; }
+
+record_cycle_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.\n              Flags: --story <id> --bcps <n> [--bcp-plus <n>] [--range <git-range>]\n                     [--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
+}

package/scripts/lib/sync-post.sh

@@ -8,6 +8,11 @@ if [ -n "${SYNC_POST_LOADED:-}" ]; then
 fi
 SYNC_POST_LOADED=1
 
+sync_post_gemini_version_mismatch() {
+  local ext_ver="$1" pkg_ver="$2"
+  [[ -n "$ext_ver" && -n "$pkg_ver" && "$ext_ver" != "$pkg_ver" ]]
+}
+
 sync_post_run() {
   local skill_count="${1:-0}"
   local opencode_count="${2:-0}"
@@ -116,7 +121,7 @@ sync_post_regression_guards() {
   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
+    if sync_post_gemini_version_mismatch "$ext_ver" "$pkg_ver"; then
       echo "sync-skills: FAIL — gemini-extension.json version ($ext_ver) != package.json ($pkg_ver)" >&2
       exit 1
     fi

package/scripts/lib/test-assertions.sh

@@ -0,0 +1,11 @@
+#!/usr/bin/env bash
+# test-assertions.sh — shared pass/fail/cleanup helpers for verification scripts
+
+if [[ -n "${TEST_ASSERTIONS_LOADED:-}" ]]; then return 0; fi
+TEST_ASSERTIONS_LOADED=1
+
+ta_cleanup() { [[ -n "${TA_TMPDIR:-}" && -d "$TA_TMPDIR" ]] && rm -rf "$TA_TMPDIR"; }
+
+ta_pass() { echo "  PASS $1"; TA_PASS=$((TA_PASS + 1)); }
+
+ta_fail() { echo "  FAIL $1"; TA_FAIL=$((TA_FAIL + 1)); }

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

@@ -59,9 +59,12 @@ validate_story_metrics() {
   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
+  if [ "$source" != "estimated" ]; then
+    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
   fi
 
   eff="$(echo "$fm" | $PYTHON -c "

package/scripts/record-cycle-time.sh

@@ -49,35 +49,10 @@ PAD_SECONDS=$(( 120 * 60 ))
 STORY_KEY="Story"
 # git-hours engine — partition + whole_range_hours (additivity oracle)
 true && source "$(dirname "${BASH_SOURCE[0]}")/lib/git-hours.sh"
+true && source "$(dirname "${BASH_SOURCE[0]}")/lib/record-cycle-time-lib.sh"
 
-die() { echo "record-cycle-time: $*" >&2; exit 1; }
-
-usage_cycle() {
-  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.\n              Flags: --story <id> --bcps <n> [--bcp-plus <n>] [--range <git-range>]\n                     [--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
-}
+die() { record_cycle_die "$@"; }
+usage_cycle() { record_cycle_usage; }
 
 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"
@@ -212,6 +187,7 @@ cmd_append() {
     printf -- '---\n'
     printf -- 'okf_kind: story-metrics\n'
     printf -- 'okf_version: "0.1"\n'
+    printf -- 'type: StoryMetrics\n'
     printf -- 'id: %s\n' "$story"
     printf -- 'epic: %s\n' "${story%%s*}"          # e40s03 → e40
     printf -- 'bcps: %s\n' "$bcps"

package/scripts/sync-skills.sh

@@ -43,9 +43,9 @@ for arg in "$@"; do
 done
 
 _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"
+source "$(dirname "${BASH_SOURCE[0]}")/lib/skill-common.sh"
+source "$(dirname "${BASH_SOURCE[0]}")/lib/sync-render.sh"
+source "$(dirname "${BASH_SOURCE[0]}")/lib/sync-post.sh"
 resolve_repo_root
 
 CURSOR_RULES="$REPO_ROOT/.cursor/rules"

package/scripts/test-adapters.sh

@@ -22,12 +22,12 @@ bash "$SCRIPT_DIR/validate-targets-yaml.sh" >/dev/null
 PASS=0
 FAIL=0
 TMPDIR=""
+TA_PASS=0
+TA_FAIL=0
+TA_TMPDIR=""
 
-cleanup() { [[ -n "$TMPDIR" && -d "$TMPDIR" ]] && rm -rf "$TMPDIR"; }
-trap cleanup EXIT
-
-pass() { echo "  PASS $1"; PASS=$((PASS + 1)); }
-fail() { echo "  FAIL $1"; FAIL=$((FAIL + 1)); }
+source "$SCRIPT_DIR/lib/test-assertions.sh"
+trap ta_cleanup EXIT
 
 test_adapter() {
   local id="$1"
@@ -38,11 +38,11 @@ test_adapter() {
     return 0
   fi
 
-  [[ -f "$adapter_file" ]] || { fail "$id: adapter missing"; return; }
-  pass "$id: exists"
+  [[ -f "$adapter_file" ]] || { ta_fail "$id: adapter missing"; return; }
+  ta_pass "$id: exists"
 
   # shellcheck source=/dev/null
-  source "$adapter_file" 2>/dev/null && pass "$id: sourceable" || { fail "$id: source error"; return; }
+  source "$adapter_file" 2>/dev/null && ta_pass "$id: sourceable" || { ta_fail "$id: source error"; return; }
 
   local has_skill has_context mode
   has_skill=$(yq -r ".targets[] | select(.id==\"$id\") | .skill != null" "$TARGETS_FILE")
@@ -50,11 +50,11 @@ test_adapter() {
   mode=$(yq -r ".targets[] | select(.id==\"$id\") | .context.mode // \"\"" "$TARGETS_FILE")
 
   if [[ "$has_skill" == "true" ]]; then
-    declare -f render_skill >/dev/null 2>&1 && pass "$id: render_skill defined" || fail "$id: render_skill missing"
+    declare -f render_skill >/dev/null 2>&1 && ta_pass "$id: render_skill defined" || ta_fail "$id: render_skill missing"
   fi
 
   if [[ "$has_context" == "true" && "$mode" != "native" ]]; then
-    declare -f wire_context >/dev/null 2>&1 && pass "$id: wire_context defined" || fail "$id: wire_context missing"
+    declare -f wire_context >/dev/null 2>&1 && ta_pass "$id: wire_context defined" || ta_fail "$id: wire_context missing"
 
     TMPDIR=$(mktemp -d)
     cp "$SCRIPT_DIR/../docs/templates/AGENTS.md" "$TMPDIR/AGENTS.md" 2>/dev/null || echo "# test" > "$TMPDIR/AGENTS.md"
@@ -63,7 +63,7 @@ test_adapter() {
       # shellcheck source=/dev/null
       source "$adapter_file"
       wire_context 2>/dev/null || true
-      wire_context 2>/dev/null && pass "$id: idempotent wire_context" || fail "$id: wire_context failed"
+      wire_context 2>/dev/null && ta_pass "$id: idempotent wire_context" || ta_fail "$id: wire_context failed"
     )
   fi
 }
@@ -76,5 +76,5 @@ else
   done < <(yq -r '.targets[] | (.skill.adapter // .context.adapter)' "$TARGETS_FILE" | sort -u)
 fi
 
-echo "test-adapters: $PASS passed, $FAIL failed"
-[[ "$FAIL" -eq 0 ]] || exit 1
+echo "test-adapters: $TA_PASS passed, $TA_FAIL failed"
+[[ "$TA_FAIL" -eq 0 ]] || exit 1

package/scripts/test-trace-matrix-size.sh

@@ -16,17 +16,17 @@ NC='\033[0m'
 CAP=300
 FAILURES=0
 
-pass() { echo -e "${GREEN}PASS${NC} $1"; }
-fail() { echo -e "${RED}FAIL${NC} $1"; FAILURES=$((FAILURES + 1)); }
+trace_size_pass() { echo -e "${GREEN}PASS${NC} $1"; }
+trace_size_fail() { echo -e "${RED}FAIL${NC} $1"; FAILURES=$((FAILURES + 1)); }
 
 check_lines() {
   local file="$1"
   local lines
   lines=$(wc -l < "$REPO_ROOT/$file" | tr -d ' ')
   if [[ "$lines" -le "$CAP" ]]; then
-    pass "$file: $lines lines (≤ $CAP)"
+    trace_size_pass "$file: $lines lines (≤ $CAP)"
   else
-    fail "$file: $lines lines (exceeds $CAP)"
+    trace_size_fail "$file: $lines lines (exceeds $CAP)"
   fi
 }
 

package/scripts/test-trace-strict.sh

@@ -19,8 +19,8 @@ NC='\033[0m'
 TRACE_ENGINE="$REPO_ROOT/scripts/lib/trace-stories.py"
 FAILURES=0
 
-pass() { echo -e "${GREEN}PASS${NC} $1"; }
-fail() { echo -e "${RED}FAIL${NC} $1"; FAILURES=$((FAILURES + 1)); }
+trace_strict_pass() { echo -e "${GREEN}PASS${NC} $1"; }
+trace_strict_fail() { echo -e "${RED}FAIL${NC} $1"; FAILURES=$((FAILURES + 1)); }
 
 run_strict() {
   local root="$1"
@@ -88,9 +88,9 @@ bash "$REPO_ROOT/scripts/trace-stories.sh" --strict --json >/dev/null 2>&1
 repo_exit=$?
 set -e
 if [[ $repo_exit -eq 0 ]]; then
-  pass "trace-stories.sh --strict exits 0 on repo"
+  trace_strict_pass "trace-stories.sh --strict exits 0 on repo"
 else
-  fail "trace-stories.sh --strict exits $repo_exit on repo (expected 0)"
+  trace_strict_fail "trace-stories.sh --strict exits $repo_exit on repo (expected 0)"
 fi
 
 echo ""
@@ -103,9 +103,9 @@ todo_output=$(run_strict "$FIXTURE_ROOT")
 todo_exit=$?
 set -e
 if [[ $todo_exit -eq 0 ]]; then
-  pass "strict passes when P0 stories are todo with 0 links"
+  trace_strict_pass "strict passes when P0 stories are todo with 0 links"
 else
-  fail "strict exits $todo_exit on all-todo fixture (expected 0)"
+  trace_strict_fail "strict exits $todo_exit on all-todo fixture (expected 0)"
   echo "$todo_output"
 fi
 
@@ -117,9 +117,9 @@ done_output=$(run_strict "$FIXTURE_ROOT")
 done_exit=$?
 set -e
 if [[ $done_exit -eq 2 ]] && grep -q "P0 stories with 0% coverage" <<<"$done_output"; then
-  pass "strict fails when a done P0 story has 0 links"
+  trace_strict_pass "strict fails when a done P0 story has 0 links"
 else
-  fail "strict exits $done_exit on done-dark fixture (expected 2 with P0 message)"
+  trace_strict_fail "strict exits $done_exit on done-dark fixture (expected 2 with P0 message)"
   echo "$done_output"
 fi
 

package/scripts/validate-doctrine.sh

@@ -9,12 +9,12 @@ cd "$REPO_ROOT"
 
 ERRORS=0
 
-fail() {
+doctrine_fail() {
   echo "FAIL: $*" >&2
   ERRORS=$((ERRORS + 1))
 }
 
-pass() {
+doctrine_pass() {
   echo "ok  : $*"
 }
 
@@ -33,10 +33,10 @@ done < <(grep -oE '`[a-z][a-z-]+`' docs/references/model-profiles.md \
   | sort -u)
 
 if [[ ${#DEAD[@]} -eq 0 ]]; then
-  pass "all skill names in model-profiles.md resolve to real directories"
+  doctrine_pass "all skill names in model-profiles.md resolve to real directories"
 else
   for name in "${DEAD[@]}"; do
-    fail "dead skill name in model-profiles.md: '$name' has no matching directory"
+    doctrine_fail "dead skill name in model-profiles.md: '$name' has no matching directory"
   done
 fi
 
@@ -49,9 +49,9 @@ LEGACY_HITS=$(grep -rE "PLAN\.md|STATE\.md|PROJECT\.md|CONTEXT\.md|SUMMARY\.md|V
   | grep -v "specs/archive" \
   | wc -l | tr -d ' ') || true
 if [[ "$LEGACY_HITS" -eq 0 ]]; then
-  pass "no legacy MD artifact names in live docs/ (docs/archive/ exempt)"
+  doctrine_pass "no legacy MD artifact names in live docs/ (docs/archive/ exempt)"
 else
-  fail "legacy MD artifact names found in docs/ ($LEGACY_HITS occurrences)"
+  doctrine_fail "legacy MD artifact names found in docs/ ($LEGACY_HITS occurrences)"
   grep -rE "PLAN\.md|STATE\.md|PROJECT\.md|CONTEXT\.md|SUMMARY\.md|VERIFICATION\.md|RESEARCH\.md|RELEASE-PLAN\.md" \
     docs/ 2>/dev/null \
     | grep -v "docs/archive/" \
@@ -68,9 +68,9 @@ fi
 STALE_COUNT_HITS=$(grep -rE "expect [0-9]+" docs/ 2>/dev/null \
   | grep -v "expect $LIVE_COUNT" | wc -l | tr -d ' ') || true
 if [[ "$STALE_COUNT_HITS" -eq 0 ]]; then
-  pass "skill count annotations match live count ($LIVE_COUNT)"
+  doctrine_pass "skill count annotations match live count ($LIVE_COUNT)"
 else
-  fail "stale skill count annotation in docs/ (live=$LIVE_COUNT, $STALE_COUNT_HITS mismatches)"
+  doctrine_fail "stale skill count annotation in docs/ (live=$LIVE_COUNT, $STALE_COUNT_HITS mismatches)"
   grep -rE "expect [0-9]+" docs/ 2>/dev/null | grep -v "expect $LIVE_COUNT" >&2
 fi
 
@@ -86,9 +86,9 @@ LEGACY_SPECS=$(grep -rE "specs/(requirements|plans|audit)\b" \
   | grep -v "CHANGELOG\.md\|specs/verifications/reports/\|PLAN-evolve-structure\.md" \
   | wc -l | tr -d ' ') || true
 if [[ "$LEGACY_SPECS" -eq 0 ]]; then
-  pass "no legacy specs/ subpaths (requirements/, plans/, audit/)"
+  doctrine_pass "no legacy specs/ subpaths (requirements/, plans/, audit/)"
 else
-  fail "legacy specs/ subpaths found ($LEGACY_SPECS occurrences)"
+  doctrine_fail "legacy specs/ subpaths found ($LEGACY_SPECS occurrences)"
   grep -rE "specs/(requirements|plans|audit)\b" \
     --include="*.md" --include="*.sh" --include="*.yaml" --include="*.yml" --include="*.json" . \
     2>/dev/null \
@@ -103,9 +103,9 @@ BCP_SLOP=$(grep -ri "build commit point" . 2>/dev/null \
   | grep -v "specs/archive\|\.git\|node_modules\|\.gemini\|\.cursor\|validate-doctrine\.sh" \
   | wc -l | tr -d ' ') || true
 if [[ "$BCP_SLOP" -eq 0 ]]; then
-  pass "no 'Build Commit Point' slop — BCP = Business Complexity Points"
+  doctrine_pass "no 'Build Commit Point' slop — BCP = Business Complexity Points"
 else
-  fail "'Build Commit Point' found ($BCP_SLOP hits) — canonical term is 'Business Complexity Points'; see docs/references/bcp.md"
+  doctrine_fail "'Build Commit Point' found ($BCP_SLOP hits) — canonical term is 'Business Complexity Points'; see docs/references/bcp.md"
   grep -ri "build commit point" . 2>/dev/null \
     | grep -v "specs/archive\|\.git\|node_modules\|\.gemini\|\.cursor\|validate-doctrine\.sh" | head -5 >&2
 fi
@@ -113,9 +113,9 @@ fi
 # ── Epic 4: SKILL.md size cap ─────────────────────────────────────────────────
 echo "--- [Epic 4] SKILL.md size cap ---"
 if bash "$REPO_ROOT/scripts/check-skill-size.sh" >/dev/null 2>&1; then
-  pass "all SKILL.md files within tiered size cap (150 critical-path / 120 utility)"
+  doctrine_pass "all SKILL.md files within tiered size cap (150 critical-path / 120 utility)"
 else
-  fail "a SKILL.md exceeds its size cap — run: bash scripts/check-skill-size.sh"
+  doctrine_fail "a SKILL.md exceeds its size cap — run: bash scripts/check-skill-size.sh"
   bash "$REPO_ROOT/scripts/check-skill-size.sh" 2>&1 | grep "^FAIL:" >&2 || true
 fi
 
@@ -130,19 +130,19 @@ for s in "${CRITICAL_HANDOFF[@]}"; do
   fi
 done
 if [[ ${#MISSING_HANDOFF[@]} -eq 0 ]]; then
-  pass "all critical-path skills document a handoff target"
+  doctrine_pass "all critical-path skills document a handoff target"
 else
   for s in "${MISSING_HANDOFF[@]}"; do
-    fail "critical-path skill '$s' has no documented handoff/next_skill"
+    doctrine_fail "critical-path skill '$s' has no documented handoff/next_skill"
   done
 fi
 
 # ── CI: trace-stories wrapper smoke (REPO_ROOT must be set under set -u) ───────
 echo "--- [CI] trace-stories wrapper smoke ---"
 if bash "$REPO_ROOT/scripts/trace-stories.sh" --help >/dev/null 2>&1; then
-  pass "trace-stories.sh --help exits 0 (REPO_ROOT initialized)"
+  doctrine_pass "trace-stories.sh --help exits 0 (REPO_ROOT initialized)"
 else
-  fail "trace-stories.sh --help failed — REPO_ROOT likely unset; run: bash scripts/trace-stories.sh --help"
+  doctrine_fail "trace-stories.sh --help failed — REPO_ROOT likely unset; run: bash scripts/trace-stories.sh --help"
 fi
 
 # ── Summary ────────────────────────────────────────────────────────────────────

package/scripts/validate-skill-catalog.sh

@@ -20,7 +20,7 @@ WARNINGS=0
 # Documented naming exceptions (craft-skill REFERENCE.md)
 VERB_NOUN_EXCEPTIONS="grill-me grill-with-docs context7-mcp using-bigpowers deploy"
 
-usage() {
+catalog_usage() {
   echo "Usage: bash scripts/validate-skill-catalog.sh [--archive] [--strict] [--skill <name>]"
   exit 2
 }
@@ -31,15 +31,15 @@ while [[ $# -gt 0 ]]; do
     --strict) STRICT=true; shift ;;
     --skill) TARGET_SKILL="${2:-}"; shift 2 ;;
     --skill=*) TARGET_SKILL="${1#*=}"; shift ;;
-    -h|--help) usage ;;
-    *) echo "Unknown flag: $1" >&2; usage ;;
+    -h|--help) catalog_usage ;;
+    *) echo "Unknown flag: $1" >&2; catalog_usage ;;
   esac
 done
 
 report_catalog_violation() { echo "FAIL: $1" >&2; VIOLATIONS=$((VIOLATIONS + 1)); }
 report_catalog_warning() { echo "WARN: $1" >&2; WARNINGS=$((WARNINGS + 1)); }
 
-check_verb_noun() {
+catalog_validate_verb_noun() {
   local name="$1"
   if echo " $VERB_NOUN_EXCEPTIONS " | grep -q " $name "; then
     return 0
@@ -55,12 +55,12 @@ check_verb_noun() {
   fi
 }
 
-check_skill() {
+catalog_validate_skill() {
   local skill_md="$1"
   local name
   name=$(basename "$(dirname "$skill_md")")
 
-  check_verb_noun "$name" || true
+  catalog_validate_verb_noun "$name" || true
 
   if ! grep -q 'HARD GATE' "$skill_md" 2>/dev/null; then
     if $STRICT; then report_catalog_violation "$name: missing HARD GATE block"; else report_catalog_warning "$name: missing HARD GATE block"; fi
@@ -68,7 +68,7 @@ check_skill() {
 
   local desc
   desc=$(awk 'BEGIN{f=0} /^---$/{f++; next} f==1{print} f==2{exit}' "$skill_md" \
-    | grep -E '^description:' | head -1 | sed 's/^description: *//; s/^> //' | tr -d '"' || true)
+    | grep -E '^description:' | head -1 | sed 's/^description: *//; s/^\x3e //' | tr -d '"' || true)
   if [[ -n "$desc" && ${#desc} -gt 1024 ]]; then
     report_catalog_violation "$name: description ${#desc} chars (max 1024)"
   fi
@@ -80,7 +80,7 @@ check_skill() {
   fi
 
   local cmd
-  cmd=$(grep -E '^(> )?→ verify:' "$skill_md" 2>/dev/null | tail -1 | sed 's/^> // ; s/^→ verify: *//' || true)
+  cmd=$(grep 'verify:' "$skill_md" 2>/dev/null | tail -1 | sed 's/^\x3e //; s/^→ verify: *//' || true)
   if [[ -z "$cmd" ]]; then
     if $STRICT; then report_catalog_violation "$name: missing → verify: command"; else report_catalog_warning "$name: missing → verify: command"; fi
   fi
@@ -90,11 +90,11 @@ echo "Validating skill catalog under $SKILLS_ROOT ..."
 if [[ -n "$TARGET_SKILL" ]]; then
   skill_md="$SKILLS_ROOT/$TARGET_SKILL/SKILL.md"
   [[ -f "$skill_md" ]] || { echo "FAIL: $skill_md not found" >&2; exit 1; }
-  check_skill "$skill_md"
+  catalog_validate_skill "$skill_md"
 else
   for skill_md in "$SKILLS_ROOT"/*/SKILL.md; do
     [[ -f "$skill_md" ]] || continue
-    check_skill "$skill_md"
+    catalog_validate_skill "$skill_md"
   done
 fi
 

package/scripts/verify-install.sh

@@ -52,83 +52,85 @@ fi
 PASS=0
 FAIL=0
 TMPDIR=""
+TA_PASS=0
+TA_FAIL=0
+TA_TMPDIR=""
 
-cleanup() { [[ -n "$TMPDIR" && -d "$TMPDIR" ]] && rm -rf "$TMPDIR"; }
-trap cleanup EXIT
+source "$(dirname "${BASH_SOURCE[0]}")/lib/test-assertions.sh"
+trap ta_cleanup EXIT
 
-pass() { echo "  PASS $1"; PASS=$((PASS + 1)); }
-fail() { echo "  FAIL $1"; FAIL=$((FAIL + 1)); }
 
 echo "=== install.sh --dry-run ==="
 DRY_OUT="$("$REPO_ROOT/scripts/install.sh" --dry-run 2>&1)"
 
-echo "$DRY_OUT" | grep -q 'pi →' && pass "install --dry-run includes pi" || fail "install --dry-run missing pi"
+echo "$DRY_OUT" | grep -q 'pi →' && ta_pass "install --dry-run includes pi" || ta_fail "install --dry-run missing pi"
 DRY_UNINSTALL="$("$REPO_ROOT/scripts/install.sh" --dry-run --uninstall 2>&1)"
-echo "$DRY_UNINSTALL" | grep -q 'pi →' && pass "uninstall --dry-run includes pi" || fail "uninstall --dry-run missing pi"
-echo "$DRY_OUT" | grep -qi 'opencode' && fail "install references opencode" || pass "install has no opencode reference"
-echo "$DRY_OUT" | grep -q 'Claude Code →' && pass "install includes Claude Code" || fail "install missing Claude Code"
-echo "$DRY_OUT" | grep -q 'Gemini CLI →' && pass "install includes Gemini CLI" || fail "install missing Gemini CLI"
-echo "$DRY_OUT" | grep -q 'Cursor →' && pass "install includes Cursor" || fail "install missing Cursor"
+echo "$DRY_UNINSTALL" | grep -q 'pi →' && ta_pass "uninstall --dry-run includes pi" || ta_fail "uninstall --dry-run missing pi"
+echo "$DRY_OUT" | grep -qi 'opencode' && ta_fail "install references opencode" || ta_pass "install has no opencode reference"
+echo "$DRY_OUT" | grep -q 'Claude Code →' && ta_pass "install includes Claude Code" || ta_fail "install missing Claude Code"
+echo "$DRY_OUT" | grep -q 'Gemini CLI →' && ta_pass "install includes Gemini CLI" || ta_fail "install missing Gemini CLI"
+echo "$DRY_OUT" | grep -q 'Cursor →' && ta_pass "install includes Cursor" || ta_fail "install missing Cursor"
 
 for tool in "Claude Code" "pi"; do
   section=$(echo "$DRY_OUT" | sed -n "/${tool} →/,/^$/p")
   count=$(echo "$section" | grep -o '[0-9]\+ skills installed' | grep -o '[0-9]\+' || echo "0")
-  [[ "$count" -gt 0 ]] && pass "${tool}: $count skills" || fail "${tool}: 0 skills"
+  [[ "$count" -gt 0 ]] && ta_pass "${tool}: $count skills" || ta_fail "${tool}: 0 skills"
 done
 
 echo ""
 echo "=== AGENTS.md spine (e37s04) ==="
-[[ -f "$REPO_ROOT/docs/templates/AGENTS.md" ]] && pass "Reach template exists" || fail "Reach template missing"
-grep -q 'Preflight' "$REPO_ROOT/docs/templates/AGENTS.md" && pass "template: Preflight" || fail "template: missing Preflight"
-grep -qi 'cline\|aider\|opencode' "$REPO_ROOT/docs/templates/AGENTS.md" && pass "template: multi-agent preamble" || fail "template: missing OSS targets"
-grep -q '## Test' "$REPO_ROOT/docs/templates/AGENTS.md" && pass "template: Test section" || fail "template: missing Test"
-grep -q '## Lint' "$REPO_ROOT/docs/templates/AGENTS.md" && pass "template: Lint section" || fail "template: missing Lint"
-grep -q '## Build' "$REPO_ROOT/docs/templates/AGENTS.md" && pass "template: Build section" || fail "template: missing Build"
+[[ -f "$REPO_ROOT/docs/templates/AGENTS.md" ]] && ta_pass "Reach template exists" || ta_fail "Reach template missing"
+grep -q 'Preflight' "$REPO_ROOT/docs/templates/AGENTS.md" && ta_pass "template: Preflight" || ta_fail "template: missing Preflight"
+grep -qi 'cline\|aider\|opencode' "$REPO_ROOT/docs/templates/AGENTS.md" && ta_pass "template: multi-agent preamble" || ta_fail "template: missing OSS targets"
+grep -q '## Test' "$REPO_ROOT/docs/templates/AGENTS.md" && ta_pass "template: Test section" || ta_fail "template: missing Test"
+grep -q '## Lint' "$REPO_ROOT/docs/templates/AGENTS.md" && ta_pass "template: Lint section" || ta_fail "template: missing Lint"
+grep -q '## Build' "$REPO_ROOT/docs/templates/AGENTS.md" && ta_pass "template: Build section" || ta_fail "template: missing Build"
 
 echo ""
 echo "=== Cline native AGENTS.md (e37s02) ==="
-[[ -f "$REPO_ROOT/AGENTS.md" || -f "$REPO_ROOT/docs/templates/AGENTS.md" ]] && pass "Cline: AGENTS.md present (native reader)" || fail "Cline: AGENTS.md missing"
-grep -qi 'cline' "$REPO_ROOT/skills/using-bigpowers/SKILL.md" && pass "using-bigpowers: Cline section" || fail "using-bigpowers: missing Cline"
+[[ -f "$REPO_ROOT/AGENTS.md" || -f "$REPO_ROOT/docs/templates/AGENTS.md" ]] && ta_pass "Cline: AGENTS.md present (native reader)" || ta_fail "Cline: AGENTS.md missing"
+grep -qi 'cline' "$REPO_ROOT/skills/using-bigpowers/SKILL.md" && ta_pass "using-bigpowers: Cline section" || ta_fail "using-bigpowers: missing Cline"
 
 echo ""
 echo "=== Aider bridge (e37s03) ==="
-grep -qi 'aider' "$REPO_ROOT/skills/seed-conventions/SKILL.md" && pass "seed-conventions: Aider wiring" || fail "seed-conventions: missing Aider"
-grep -qi 'Aider-AI' "$REPO_ROOT/skills/using-bigpowers/SKILL.md" && pass "using-bigpowers: Aider-AI upstream" || fail "using-bigpowers: missing Aider-AI"
+grep -qi 'aider' "$REPO_ROOT/skills/seed-conventions/SKILL.md" && ta_pass "seed-conventions: Aider wiring" || ta_fail "seed-conventions: missing Aider"
+grep -qi 'Aider-AI' "$REPO_ROOT/skills/using-bigpowers/SKILL.md" && ta_pass "using-bigpowers: Aider-AI upstream" || ta_fail "using-bigpowers: missing Aider-AI"
 
 echo ""
 echo "=== Optional Codex wave (e37s04) ==="
 if grep -qi 'codex' "$REPO_ROOT/skills/seed-conventions/SKILL.md" 2>/dev/null; then
-  grep -qi 'config.toml' "$REPO_ROOT/skills/seed-conventions/REFERENCE.md" && pass "Codex: REFERENCE config.toml" || fail "Codex: missing config.toml"
-  echo "$DRY_OUT" | grep -qi 'codex' && pass "Codex: install --dry-run mentions codex" || fail "Codex: install missing codex"
+  grep -qi 'config.toml' "$REPO_ROOT/skills/seed-conventions/REFERENCE.md" && ta_pass "Codex: REFERENCE config.toml" || ta_fail "Codex: missing config.toml"
+  echo "$DRY_OUT" | grep -qi 'codex' && ta_pass "Codex: install --dry-run mentions codex" || ta_fail "Codex: install missing codex"
 else
-  pass "Codex: wave absent — assertions skipped"
+  ta_pass "Codex: wave absent — assertions skipped"
 fi
 
 echo ""
 echo "=== seed-conventions local wiring ==="
-grep -qi 'local tool wiring' "$REPO_ROOT/skills/seed-conventions/SKILL.md" && pass "SKILL.md: local tool wiring" || fail "SKILL.md: missing local tool wiring"
-grep -qi 'opencode.json' "$REPO_ROOT/skills/seed-conventions/REFERENCE.md" && pass "REFERENCE.md: opencode.json" || fail "REFERENCE.md: missing opencode.json"
-grep -qi 'AGENTS.md' "$REPO_ROOT/skills/seed-conventions/SKILL.md" && pass "SKILL.md: AGENTS.md spine" || fail "SKILL.md: missing AGENTS.md"
-grep -qi 'symlink' "$REPO_ROOT/skills/seed-conventions/SKILL.md" && pass "SKILL.md: CLAUDE.md symlink" || fail "SKILL.md: missing symlink"
-grep -qi 'cursor/rules' "$REPO_ROOT/skills/seed-conventions/REFERENCE.md" && pass "REFERENCE.md: Cursor symlink" || fail "REFERENCE.md: missing Cursor symlink"
+grep -qi 'local tool wiring' "$REPO_ROOT/skills/seed-conventions/SKILL.md" && ta_pass "SKILL.md: local tool wiring" || ta_fail "SKILL.md: missing local tool wiring"
+grep -qi 'opencode.json' "$REPO_ROOT/skills/seed-conventions/REFERENCE.md" && ta_pass "REFERENCE.md: opencode.json" || ta_fail "REFERENCE.md: missing opencode.json"
+grep -qi 'AGENTS.md' "$REPO_ROOT/skills/seed-conventions/SKILL.md" && ta_pass "SKILL.md: AGENTS.md spine" || ta_fail "SKILL.md: missing AGENTS.md"
+grep -qi 'symlink' "$REPO_ROOT/skills/seed-conventions/SKILL.md" && ta_pass "SKILL.md: CLAUDE.md symlink" || ta_fail "SKILL.md: missing symlink"
+grep -qi 'cursor/rules' "$REPO_ROOT/skills/seed-conventions/REFERENCE.md" && ta_pass "REFERENCE.md: Cursor symlink" || ta_fail "REFERENCE.md: missing Cursor symlink"
 
 OPENCODE_JSON=$(sed -n '/```json/,/```/p' "$REPO_ROOT/skills/seed-conventions/REFERENCE.md" | grep -v '```' || true)
 if [[ -n "$OPENCODE_JSON" ]]; then
   TMPDIR=$(mktemp -d)
+  TA_TMPDIR="$TMPDIR"
   echo "$OPENCODE_JSON" > "$TMPDIR/test-opencode.json"
-  jq empty "$TMPDIR/test-opencode.json" 2>/dev/null && pass "opencode.json valid JSON" || fail "opencode.json NOT valid JSON"
+  jq empty "$TMPDIR/test-opencode.json" 2>/dev/null && ta_pass "opencode.json valid JSON" || ta_fail "opencode.json NOT valid JSON"
 else
-  fail "opencode.json template not found"
+  ta_fail "opencode.json template not found"
 fi
 
 echo ""
 echo "=== install.sh source ==="
-grep -q 'install_pi()' "$REPO_ROOT/scripts/install.sh" && pass "source: install_pi()" || fail "source: missing install_pi()"
-grep -q 'uninstall_pi()' "$REPO_ROOT/scripts/install.sh" && pass "source: uninstall_pi()" || fail "source: missing uninstall_pi()"
-grep -q 'PI_SKILLS_DIR="$PI_CONFIG_DIR/agent/skills"' "$REPO_ROOT/scripts/install.sh" && pass "source: targets ~/.pi/agent/skills/" || fail "source: wrong pi target"
-! grep -q 'install_opencode\|print_opencode_instructions' "$REPO_ROOT/scripts/install.sh" && pass "source: no opencode functions" || fail "source: opencode functions remain"
+grep -q 'install_pi()' "$REPO_ROOT/scripts/install.sh" && ta_pass "source: install_pi()" || ta_fail "source: missing install_pi()"
+grep -q 'uninstall_pi()' "$REPO_ROOT/scripts/install.sh" && ta_pass "source: uninstall_pi()" || ta_fail "source: missing uninstall_pi()"
+grep -q 'PI_SKILLS_DIR="$PI_CONFIG_DIR/agent/skills"' "$REPO_ROOT/scripts/install.sh" && ta_pass "source: targets ~/.pi/agent/skills/" || ta_fail "source: wrong pi target"
+! grep -q 'install_opencode\|print_opencode_instructions' "$REPO_ROOT/scripts/install.sh" && ta_pass "source: no opencode functions" || ta_fail "source: opencode functions remain"
 
 echo ""
 echo "──────────────────────────────────────────"
-echo "verify-install: $PASS passed, $FAIL failed"
-[[ "$FAIL" -gt 0 ]] && { echo "Overall: fail"; exit 1; } || echo "Overall: pass"
+echo "verify-install: $TA_PASS passed, $TA_FAIL failed"
+[[ "$TA_FAIL" -gt 0 ]] && { echo "Overall: fail"; exit 1; } || echo "Overall: pass"

package/tests/test-okf-generators.sh

@@ -40,6 +40,11 @@ bash "$REPO_ROOT/scripts/sync-bugs-registry.sh" >/dev/null
 require_min_count "$REPO_ROOT/specs/bugs" 1 "bug"
 bash "$REPO_ROOT/scripts/validate-okf.sh" --dir "$REPO_ROOT/specs/bugs"
 
+echo "→ validate all CI OKF directories"
+for dir in specs/metrics specs/migrations specs/verifications/reports; do
+  bash "$REPO_ROOT/scripts/validate-okf.sh" --dir "$REPO_ROOT/$dir"
+done
+
 echo "→ publish-to-wiki.sh --dry-run"
 OUTPUT="$(bash "$REPO_ROOT/kernel/src/publish-to-wiki.sh" --dry-run)"
 if [[ "$OUTPUT" != *"pages:"* ]]; then