bigpowers 2.79.1 → 2.81.0

package/.pi/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bigpowers",
-  "version": "2.79.1",
+  "version": "2.81.0",
   "description": "80 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,17 @@
+# [2.81.0](https://github.com/danielvm-git/bigpowers/compare/v2.80.0...v2.81.0) (2026-07-23)
+
+
+### Features
+
+* **e54s02:** advisory catalog drift-detection gate ([7761f75](https://github.com/danielvm-git/bigpowers/commit/7761f75ed2312d419f3e28f192385304e36e83f2))
+
+# [2.80.0](https://github.com/danielvm-git/bigpowers/compare/v2.79.1...v2.80.0) (2026-07-23)
+
+
+### Features
+
+* **e54s01:** freeze skill catalog baseline snapshot ([0df0fff](https://github.com/danielvm-git/bigpowers/commit/0df0fff86fc48794a2343ae4b2c421835bc5c58c))
+
 ## [2.79.1](https://github.com/danielvm-git/bigpowers/compare/v2.79.0...v2.79.1) (2026-07-23)
 
 

package/CLAUDE.md

@@ -65,7 +65,7 @@ Stack: Markdown / Bash (documentation-based; skills integrate with Claude Code,
 | Compliance | `npm run compliance` |
 | Verification Gates | `bash scripts/run-verification-gates.sh` |
 | Traceability | `bash scripts/trace-stories.sh --strict` | grep for story tags (traceability check) |
-| Preflight | `npm run compliance && bash scripts/run-verification-gates.sh && bash scripts/sync-skills.sh && bash scripts/trace-stories.sh --strict` | Full local green stack before forward work |
+| Preflight | `npm run compliance && bash scripts/run-verification-gates.sh && bash scripts/sync-skills.sh && bash scripts/trace-stories.sh --strict && bash scripts/check-catalog-drift.sh` | Full local green stack before forward work. Trailing step is advisory only (e54s02 catalog-freeze drift check) — it always exits 0 and can never break this chain. |
 | CI | `gh pr checks` | Remote CI green when a PR is open |
 
 ### Pre-Merge Checklist

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bigpowers",
-  "version": "2.79.1",
+  "version": "2.81.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/check-catalog-drift.sh

@@ -0,0 +1,81 @@
+#!/usr/bin/env bash
+# story: e54s02
+# check-catalog-drift.sh — advisory (Confirm-gate) diff of the live skill
+# catalog against e54s01's frozen baseline. ALWAYS exits 0: this warns during
+# the freeze window, it never blocks Preflight (never add to GOLDEN_GATES).
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$SCRIPT_DIR/lib/skill-common.sh"
+source "$SCRIPT_DIR/lib/python-env.sh"
+
+resolve_repo_root
+cd "$REPO_ROOT"
+
+BASELINE="$(ls -1 "$REPO_ROOT"/specs/tech-architecture/CATALOG-BASELINE-*.yaml 2>/dev/null | sort | tail -1 || true)"
+
+if [[ -z "$BASELINE" ]]; then
+  echo "no baseline found, skipping drift check"
+  exit 0
+fi
+
+"$PYTHON" - "$BASELINE" "$SKILLS_ROOT" <<'PY'
+import sys, glob, os, re
+import yaml
+
+baseline_path, skills_root = sys.argv[1], sys.argv[2]
+baseline = yaml.safe_load(open(baseline_path)) or {}
+base_by_name = {s["name"]: s for s in baseline.get("skills") or []}
+
+EXCEPTION_MARKER = "freeze-exception"
+
+def has_exception(skill_md):
+    if not os.path.isfile(skill_md):
+        return False
+    with open(skill_md, encoding="utf-8") as f:
+        return EXCEPTION_MARKER in f.read()
+
+def parse_live(skill_md):
+    text = open(skill_md, encoding="utf-8").read()
+    fm = re.search(r"^---\n(.*?)\n---", text, re.S | re.M)
+    fields = {}
+    if fm:
+        for line in fm.group(1).splitlines():
+            m = re.match(r"^(phase|effort|model):\s*(.+)$", line)
+            if m:
+                fields[m.group(1)] = m.group(2).strip()
+    return fields
+
+live_by_name = {}
+for skill_md in sorted(glob.glob(os.path.join(skills_root, "*", "SKILL.md"))):
+    name = os.path.basename(os.path.dirname(skill_md))
+    live_by_name[name] = {"path": skill_md, **parse_live(skill_md)}
+
+warnings = []
+
+for name, live in live_by_name.items():
+    if name not in base_by_name:
+        if not has_exception(live["path"]):
+            warnings.append(f"WARNING: addition — new skill '{name}' not in frozen baseline")
+        continue
+    base = base_by_name[name]
+    for field in ("phase", "effort", "model"):
+        base_val = base.get(field)
+        base_val = None if base_val in ("null", None) else str(base_val)
+        live_val = live.get(field)
+        if base_val != live_val:
+            if not has_exception(live["path"]):
+                warnings.append(
+                    f"WARNING: structural change — '{name}' field '{field}' "
+                    f"changed from {base_val!r} to {live_val!r}"
+                )
+
+for name, base in base_by_name.items():
+    if name not in live_by_name:
+        warnings.append(f"WARNING: removal — skill '{name}' present in baseline but missing from live catalog")
+
+for w in warnings:
+    print(w)
+PY
+
+exit 0

package/scripts/snapshot-catalog-baseline.sh

@@ -0,0 +1,104 @@
+#!/usr/bin/env bash
+# story: e54s01
+# snapshot-catalog-baseline.sh — freeze the live skill catalog into a dated,
+# immutable YAML baseline for e56's reclassification diff.
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$SCRIPT_DIR/lib/skill-common.sh"
+source "$SCRIPT_DIR/lib/python-env.sh"
+
+resolve_repo_root
+cd "$REPO_ROOT"
+
+DRY_RUN=false
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --dry-run) DRY_RUN=true; shift ;;
+    -h|--help) echo "Usage: bash scripts/snapshot-catalog-baseline.sh [--dry-run]"; exit 0 ;;
+    *) echo "Unknown flag: $1" >&2; exit 2 ;;
+  esac
+done
+
+DATE_STR="$(date +%Y-%m-%d)"
+COMMIT_HASH="$(git rev-parse HEAD 2>/dev/null || echo unknown)"
+OUT_FILE="$REPO_ROOT/specs/tech-architecture/CATALOG-BASELINE-${DATE_STR}.yaml"
+
+# unquote_source_desc — strip a source frontmatter's own surrounding quotes
+# and unescape its inner \" , or re-quoting double-escapes the description.
+unquote_source_desc() {
+  local desc="$1"
+  if [[ "$desc" == \"*\" ]]; then
+    desc="${desc#\"}"
+    desc="${desc%\"}"
+    desc="${desc//\\\"/\"}"
+  fi
+  echo "$desc"
+}
+
+# emit_skill_row — print one skill's YAML row to stdout; appends any missing-
+# field warning line for that skill to $WARN_FILE (a plain file, since this
+# function runs inside a command-substitution subshell and can't mutate the
+# caller's shell variables).
+emit_skill_row() {
+  local skill_md="$1" name phase model effort desc desc_escaped
+  name="$(basename "$(dirname "$skill_md")")"
+  parse_frontmatter_okf "$skill_md" || true
+
+  phase="$(awk '/^---/{f++} f==1 && /^phase:/{print; exit}' "$skill_md" | sed 's/^phase:[[:space:]]*//')"
+  model="${_PF_MODEL:-}"
+  effort="${_PF_EFFORT:-}"
+  desc="${_PF_DESCRIPTION:-}"
+
+  [[ -z "$phase" ]] && phase="null"
+  [[ -z "$model" ]] && { model="null"; echo "  - \"${name}: missing model field\"" >> "$WARN_FILE"; }
+  [[ -z "$effort" ]] && { effort="null"; echo "  - \"${name}: missing effort field\"" >> "$WARN_FILE"; }
+  [[ -z "$desc" ]] && desc="null"
+
+  desc="$(unquote_source_desc "$desc")"
+  desc_escaped="${desc//\"/\\\"}"
+
+  echo "  - name: \"${name}\"\n    path: \"skills/${name}/SKILL.md\"\n    phase: ${phase}\n    effort: ${effort}\n    model: ${model}\n    description: \"${desc_escaped}\"\n"
+}
+
+WARN_FILE="$(mktemp)"
+trap 'rm -f "$WARN_FILE"' EXIT
+
+ROWS=""
+COUNT=0
+
+for skill_md in "$SKILLS_ROOT"/*/SKILL.md; do
+  [[ -f "$skill_md" ]] || continue
+  ROWS="${ROWS}$(emit_skill_row "$skill_md")"
+  COUNT=$((COUNT + 1))
+done
+
+WARNINGS="$(cat "$WARN_FILE")"
+WARN_COUNT="$(grep -c '^  -' "$WARN_FILE" || true)"
+
+if $DRY_RUN; then
+  echo "${COUNT} skills scanned"
+  echo "${WARN_COUNT} warnings"
+  [[ -n "$WARNINGS" ]] && echo -e "warnings:\n${WARNINGS}"
+  exit 0
+fi
+
+mkdir -p "$REPO_ROOT/specs/tech-architecture"
+
+{
+  echo "# CATALOG-BASELINE-${DATE_STR}.yaml"
+  echo "# frozen for e54-e59 migration; do not hand-edit"
+  echo "snapshot_date: \"${DATE_STR}\""
+  echo "commit_hash: \"${COMMIT_HASH}\""
+  echo "total_skill_count: ${COUNT}"
+  echo "warnings:"
+  if [[ -n "$WARNINGS" ]]; then
+    echo -e "$WARNINGS"
+  else
+    echo "  []"
+  fi
+  echo "skills:"
+  echo -e "$ROWS"
+} > "$OUT_FILE"
+
+echo "Wrote ${OUT_FILE} (${COUNT} skills, ${WARN_COUNT} warnings)"

package/scripts/test-tombstone-mechanism.sh

@@ -102,6 +102,48 @@ else
   tt_fail "expired tombstone was not flagged"
 fi
 
+# --- Scenario: rejects path-traversal / invalid skill names (threat model CWE-22) ---
+# tombstone-skill.sh exits non-zero on rejection, and this script runs under
+# `set -o pipefail` — capture output via `|| true` first so the pipe's exit
+# status doesn't mask the grep check below.
+output=$(bash scripts/tombstone-skill.sh "../../etc/passwd" "target" 2>&1 || true)
+if echo "$output" | grep -qi "not a valid skill name"; then
+  tt_pass "tombstone-skill.sh rejects a path-traversal old-name"
+else
+  tt_fail "tombstone-skill.sh did not reject a path-traversal old-name"
+fi
+
+output=$(bash scripts/tombstone-skill.sh "$FIXTURE_OLD" "../../etc/passwd" 2>&1 || true)
+if echo "$output" | grep -qi "not a valid skill name"; then
+  tt_pass "tombstone-skill.sh rejects a path-traversal new-name"
+else
+  tt_fail "tombstone-skill.sh did not reject a path-traversal new-name"
+fi
+
+# --- Scenario: validate-tombstones.sh rejects an invalid name read back from the ledger ---
+python3 -c "
+import yaml
+d = yaml.safe_load(open('$TOMBSTONES_FILE')) or {'tombstones': []}
+d.setdefault('tombstones', []).append({
+    'old_name': '../../etc/passwd',
+    'new_name_or_merge_target': 'target',
+    'created_at_version': '0.0.0',
+})
+yaml.dump(d, open('$TOMBSTONES_FILE', 'w'), default_flow_style=False)
+"
+output=$(bash scripts/validate-tombstones.sh 2>&1 | strip_ansi || true)
+if echo "$output" | grep -qi "FAIL.*not a valid skill name"; then
+  tt_pass "validate-tombstones.sh rejects a path-traversal name read from the ledger"
+else
+  tt_fail "validate-tombstones.sh did not reject a path-traversal name read from the ledger"
+fi
+python3 -c "
+import yaml
+d = yaml.safe_load(open('$TOMBSTONES_FILE')) or {'tombstones': []}
+d['tombstones'] = [t for t in d.get('tombstones', []) if t.get('old_name') != '../../etc/passwd']
+yaml.dump(d, open('$TOMBSTONES_FILE', 'w'), default_flow_style=False)
+"
+
 echo "---"
 if [[ "$FAILURES" -eq 0 ]]; then
   echo -e "${GREEN}test-tombstone-mechanism: ALL PASS${NC}"