bigpowers 2.75.1 → 2.76.0

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 "
@@ -265,7 +268,7 @@ okf_scan_dir() {
       validate_bundle "$f"
       count=$((count + 1))
     fi
-  done < <(find "$dir" -maxdepth 1 -name '*.md' -print0 2>/dev/null || true)
+  done < <(find "$dir" -maxdepth 1 \( -name '*.okf.md' -o -name 'registry.okf.md' \) -print0 2>/dev/null || true)
   if [ "$count" -eq 0 ]; then
     printf "${YELLOW}SKIP${NC} no OKF bundles found in %s\n" "$dir"
   fi

package/scripts/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-bugs-registry.sh

@@ -77,6 +77,7 @@ for e in entries:
     bundle = f"""---
 okf_kind: concept
 okf_version: "0.1"
+type: Bug
 id: "{bug_id}"
 title: "{title_escaped}"
 category: bug

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