bigpowers 2.78.1 → 2.79.0

package/.pi/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bigpowers",
-  "version": "2.78.1",
+  "version": "2.79.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,10 @@
+# [2.79.0](https://github.com/danielvm-git/bigpowers/compare/v2.78.1...v2.79.0) (2026-07-23)
+
+
+### Features
+
+* **scripts:** implement tombstone-skill.sh and validate-tombstones.sh ([c81a451](https://github.com/danielvm-git/bigpowers/commit/c81a451598d8338188fb9e18b4486e20e6c177f8))
+
 ## [2.78.1](https://github.com/danielvm-git/bigpowers/compare/v2.78.0...v2.78.1) (2026-07-23)
 
 

package/CONVENTIONS.md

@@ -353,6 +353,35 @@ name must return < 5 results across the repo.
 
 Any new exception requires an entry in this table before the skill is published.
 
+## Tombstone Aliases (e53s02)
+
+Every skill rename or merge ships a tombstone alias for one release, so consumers
+referencing the old name don't break immediately.
+
+**Mechanism:**
+
+1. Run `bash scripts/tombstone-skill.sh <old-name> <new-name-or-merge-target>` when
+   renaming or merging a skill. It replaces `skills/<old-name>/SKILL.md` with a stub
+   pointing at the new name/location, preserves the old skill's `# story: eNNsNN` tags
+   for traceability, and registers the mapping in `specs/tombstones.yaml` (old name,
+   new name/target, creation timestamp, and the `bigpowers_version` at creation time).
+2. Run `bash scripts/validate-tombstones.sh` to confirm every registered tombstone's
+   stub still resolves, and to flag any tombstone whose `created_at_version` differs
+   from the current release — that stub has served its one-release transition window
+   and should be removed.
+3. **Required alongside the first real use of `tombstone-skill.sh`:** update
+   `docs/references/model-profiles.md`'s skill-count annotations. A tombstone stub is
+   still a `skills/*/SKILL.md` file — it increments the live skill count the same as
+   any other skill, and the count doc must reflect that.
+
+**Rejected names:** both the old and new name must be a bare kebab-case skill name
+(`^[a-z][a-z0-9-]*$`) — `tombstone-skill.sh` refuses anything else before touching the
+filesystem (path segments, absolute paths, etc.).
+
+This story (e53s02) builds the mechanism only; it creates no real tombstone stub
+itself, so the live skill count doesn't move yet. The first real use is expected in
+e56 (skill reclassification/merges).
+
 ## File-Size Exceptions
 
 The 300-line file cap exists to ensure files fit in a single agent context

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bigpowers",
-  "version": "2.78.1",
+  "version": "2.79.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/test-tombstone-mechanism.sh

@@ -0,0 +1,111 @@
+#!/usr/bin/env bash
+# story: e53s02
+# test-tombstone-mechanism.sh — exercises tombstone-skill.sh and
+# validate-tombstones.sh end-to-end against throwaway fixtures.
+#
+# Usage: bash scripts/test-tombstone-mechanism.sh
+
+set -euo pipefail
+source "$(dirname "${BASH_SOURCE[0]}")/lib/skill-common.sh"
+resolve_repo_root
+cd "$REPO_ROOT"
+
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+NC='\033[0m'
+
+FAILURES=0
+tt_pass() { echo -e "${GREEN}PASS${NC} $1"; }
+tt_fail() { echo -e "${RED}FAIL${NC} $1"; FAILURES=$((FAILURES + 1)); }
+strip_ansi() { sed -E 's/\x1b\[[0-9;]*m//g'; }
+
+FIXTURE_OLD="test-tombstone-fixture"
+FIXTURE_NEW="test-tombstone-target"
+FIXTURE_DIR="skills/${FIXTURE_OLD}"
+TOMBSTONES_FILE="specs/tombstones.yaml"
+TOMBSTONES_BACKUP=""
+
+cleanup() {
+  rm -rf "$FIXTURE_DIR" "skills/${FIXTURE_NEW}"
+  if [[ -n "$TOMBSTONES_BACKUP" ]]; then
+    mv "$TOMBSTONES_BACKUP" "$TOMBSTONES_FILE"
+  else
+    rm -f "$TOMBSTONES_FILE"
+  fi
+}
+trap cleanup EXIT
+
+if [[ -f "$TOMBSTONES_FILE" ]]; then
+  TOMBSTONES_BACKUP=$(mktemp)
+  cp "$TOMBSTONES_FILE" "$TOMBSTONES_BACKUP"
+  rm -f "$TOMBSTONES_FILE"
+fi
+
+# --- Scenario: zero tombstones registered (6a) ---
+if bash scripts/validate-tombstones.sh 2>&1 | grep -qi "no tombstones"; then
+  tt_pass "validate-tombstones.sh reports clean when zero tombstones registered"
+else
+  tt_fail "validate-tombstones.sh did not report 'no tombstones' with an empty ledger"
+fi
+
+# --- Scenario: tombstone-skill.sh generates a stub ---
+mkdir -p "$FIXTURE_DIR"
+cat > "${FIXTURE_DIR}/SKILL.md" <<'FIXTUREEOF'
+# story: e00s00
+---
+name: test-tombstone-fixture
+description: throwaway fixture for test-tombstone-mechanism.sh
+---
+Fixture body.
+FIXTUREEOF
+
+bash scripts/tombstone-skill.sh "$FIXTURE_OLD" "$FIXTURE_NEW"
+
+if grep -q "TOMBSTONE" "${FIXTURE_DIR}/SKILL.md"; then
+  tt_pass "tombstone-skill.sh replaced SKILL.md with a stub"
+else
+  tt_fail "SKILL.md was not replaced with a tombstone stub"
+fi
+
+if grep -q "story: e00s00" "${FIXTURE_DIR}/SKILL.md"; then
+  tt_pass "tombstone-skill.sh preserved the old story tag"
+else
+  tt_fail "story tag was not preserved in the stub"
+fi
+
+if [[ -f "$TOMBSTONES_FILE" ]] && grep -q "$FIXTURE_OLD" "$TOMBSTONES_FILE"; then
+  tt_pass "tombstone-skill.sh registered the mapping in ${TOMBSTONES_FILE}"
+else
+  tt_fail "mapping not registered in ${TOMBSTONES_FILE}"
+fi
+
+# --- Scenario: fresh tombstone resolves cleanly ---
+if bash scripts/validate-tombstones.sh 2>&1 | strip_ansi | grep -q "OK: ${FIXTURE_OLD}"; then
+  tt_pass "validate-tombstones.sh confirms the fresh stub resolves"
+else
+  tt_fail "validate-tombstones.sh did not confirm the fresh stub"
+fi
+
+# --- Scenario: expired tombstone flagged (6b) ---
+python3 -c "
+import yaml
+d = yaml.safe_load(open('$TOMBSTONES_FILE')) or {'tombstones': []}
+for t in d['tombstones']:
+    if t['old_name'] == '$FIXTURE_OLD':
+        t['created_at_version'] = '0.0.0'
+yaml.dump(d, open('$TOMBSTONES_FILE', 'w'), default_flow_style=False)
+"
+
+if bash scripts/validate-tombstones.sh 2>&1 | strip_ansi | grep -qi "EXPIRED: ${FIXTURE_OLD}"; then
+  tt_pass "validate-tombstones.sh flags a tombstone whose expiry window has passed"
+else
+  tt_fail "expired tombstone was not flagged"
+fi
+
+echo "---"
+if [[ "$FAILURES" -eq 0 ]]; then
+  echo -e "${GREEN}test-tombstone-mechanism: ALL PASS${NC}"
+else
+  echo -e "${RED}test-tombstone-mechanism: $FAILURES failure(s)${NC}"
+fi
+exit "$FAILURES"

package/scripts/tombstone-skill.sh

@@ -0,0 +1,89 @@
+#!/usr/bin/env bash
+# story: e53s02
+# tombstone-skill.sh — replace a renamed/merged skill's SKILL.md with a stub,
+# preserving its story tags and registering the mapping in specs/tombstones.yaml
+# for a one-release expiry window.
+#
+# Usage: bash scripts/tombstone-skill.sh <old-name> <new-name-or-merge-target>
+
+set -euo pipefail
+source "$(dirname "${BASH_SOURCE[0]}")/lib/skill-common.sh"
+resolve_repo_root
+cd "$REPO_ROOT"
+
+usage() {
+  cat <<'EOF'
+Usage: tombstone-skill.sh <old-name> <new-name-or-merge-target>
+
+Replaces skills/<old-name>/SKILL.md with a stub pointing at <new-name>,
+preserves the old name's story tags, and registers the mapping in
+specs/tombstones.yaml with a one-release expiry window.
+EOF
+}
+
+if [[ "${1:-}" == "--help" || "${1:-}" == "-h" ]]; then
+  usage
+  exit 0
+fi
+
+OLD_NAME="${1:-}"
+NEW_NAME="${2:-}"
+NAME_PATTERN='^[a-z][a-z0-9-]*$'
+
+if [[ -z "$OLD_NAME" || -z "$NEW_NAME" ]]; then
+  usage >&2
+  exit 1
+fi
+
+# Threat-model mitigation (specs/security/epics/e53/THREAT_MODEL.md): reject
+# anything that isn't a bare kebab-case skill name before any path use.
+for name in "$OLD_NAME" "$NEW_NAME"; do
+  if [[ ! "$name" =~ $NAME_PATTERN ]]; then
+    echo "ERROR: '$name' is not a valid skill name (must match $NAME_PATTERN)" >&2
+    exit 1
+  fi
+done
+
+OLD_SKILL_MD="skills/${OLD_NAME}/SKILL.md"
+if [[ ! -f "$OLD_SKILL_MD" ]]; then
+  echo "ERROR: $OLD_SKILL_MD does not exist" >&2
+  exit 1
+fi
+
+STORY_TAGS=$(grep -E '^#\s*story:' "$OLD_SKILL_MD" || true)
+CURRENT_VERSION=$(grep '"version"' package.json 2>/dev/null | head -1 | sed 's/.*: *"\(.*\)".*/\1/')
+CREATED_AT=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+
+cat > "$OLD_SKILL_MD" <<STUBEOF
+---
+name: ${OLD_NAME}
+description: "TOMBSTONE — renamed/merged to ${NEW_NAME}. This stub resolves for one release then is removed."
+---
+
+# ${OLD_NAME} (tombstoned)
+
+This skill has been renamed or merged into \`${NEW_NAME}\`. Use \`${NEW_NAME}\` instead.
+
+This stub exists for one release as a transition aid, then is removed once
+\`scripts/validate-tombstones.sh\` flags it as expired.
+
+${STORY_TAGS}
+STUBEOF
+
+TOMBSTONES_FILE="specs/tombstones.yaml"
+[[ -f "$TOMBSTONES_FILE" ]] || echo "tombstones: []" > "$TOMBSTONES_FILE"
+
+python3 -c "
+import yaml
+d = yaml.safe_load(open('$TOMBSTONES_FILE')) or {'tombstones': []}
+d.setdefault('tombstones', []).append({
+    'old_name': '$OLD_NAME',
+    'new_name_or_merge_target': '$NEW_NAME',
+    'created_at': '$CREATED_AT',
+    'created_at_version': '$CURRENT_VERSION',
+})
+yaml.dump(d, open('$TOMBSTONES_FILE', 'w'), default_flow_style=False)
+"
+
+echo "Tombstoned: ${OLD_NAME} -> ${NEW_NAME}"
+echo "Registered in ${TOMBSTONES_FILE}"

package/scripts/validate-tombstones.sh

@@ -0,0 +1,63 @@
+#!/usr/bin/env bash
+# story: e53s02
+# validate-tombstones.sh — confirm each registered tombstone's stub still
+# resolves, and flag any whose one-release expiry window has passed.
+#
+# Usage: bash scripts/validate-tombstones.sh
+
+set -euo pipefail
+source "$(dirname "${BASH_SOURCE[0]}")/lib/skill-common.sh"
+resolve_repo_root
+cd "$REPO_ROOT"
+
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+NC='\033[0m'
+
+TOMBSTONES_FILE="specs/tombstones.yaml"
+FAIL=0
+
+if [[ ! -f "$TOMBSTONES_FILE" ]]; then
+  echo -e "${GREEN}OK${NC}: no tombstones registered"
+  exit 0
+fi
+
+CURRENT_VERSION=$(grep '"version"' package.json 2>/dev/null | head -1 | sed 's/.*: *"\(.*\)".*/\1/')
+
+ROWS=$(python3 -c "
+import yaml
+d = yaml.safe_load(open('$TOMBSTONES_FILE')) or {'tombstones': []}
+for t in d.get('tombstones', []) or []:
+    print(f\"{t['old_name']}\t{t['new_name_or_merge_target']}\t{t.get('created_at_version', '')}\")
+")
+
+if [[ -z "$ROWS" ]]; then
+  echo -e "${GREEN}OK${NC}: no tombstones registered"
+  exit 0
+fi
+
+while IFS=$'\t' read -r old_name new_name created_version; do
+  [[ -z "$old_name" ]] && continue
+  stub="skills/${old_name}/SKILL.md"
+
+  if [[ ! -f "$stub" ]]; then
+    echo -e "${RED}FAIL${NC}: ${old_name} -> ${new_name} — stub missing at ${stub}"
+    FAIL=1
+    continue
+  fi
+  if ! grep -q "TOMBSTONE" "$stub"; then
+    echo -e "${RED}FAIL${NC}: ${old_name} — stub exists but is not a tombstone"
+    FAIL=1
+    continue
+  fi
+
+  if [[ -n "$created_version" && "$created_version" != "$CURRENT_VERSION" ]]; then
+    echo -e "${YELLOW}EXPIRED${NC}: ${old_name} -> ${new_name} — created at ${created_version}, now ${CURRENT_VERSION}; remove the stub"
+    continue
+  fi
+
+  echo -e "${GREEN}OK${NC}: ${old_name} -> ${new_name} resolves"
+done <<< "$ROWS"
+
+exit "$FAIL"