bigpowers 2.78.1 → 2.79.1

package/.pi/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bigpowers",
-  "version": "2.78.1",
+  "version": "2.79.1",
   "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.79.1](https://github.com/danielvm-git/bigpowers/compare/v2.79.0...v2.79.1) (2026-07-23)
+
+
+### Bug Fixes
+
+* **e53:** close migration-readiness gaps — code-injection, expiry semantics, fail-open gate ([4042c62](https://github.com/danielvm-git/bigpowers/commit/4042c62f5ccac9790596f81aac5aaebd1235c763))
+
+# [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,39 @@ 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 `created_at_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` is in a
+   different minor/major release train (major.minor) than the current version — that
+   stub has served its one-release transition window and should be removed. Patch-only
+   bumps within the same minor version don't count as a new release: this repo ships
+   via semantic-release on every merge to main, so comparing full semver strings would
+   expire a tombstone within minutes of creation instead of giving consumers a real
+   migration window.
+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.1",
   "description": "73 agent skills synthesizing 17 years of software engineering discipline into a prescriptive methodology for solo developers",
   "main": "index.js",
   "scripts": {

package/scripts/lib/completeness-critic.sh

@@ -33,12 +33,25 @@ if [[ -f specs/traceability-matrix.json ]]; then
   # not-yet-built siblings (which have no code tags by definition until their
   # own turn) and not unrelated epics (which may be plan-worked-to-build-ready
   # but not yet kicked off).
-  ACTIVE_STORY="$(grep '^active_story:' specs/state.yaml 2>/dev/null | awk '{print $2}')"
-  if [[ -n "$ACTIVE_STORY" ]]; then
-    UNDONE="$(jq --arg s "$ACTIVE_STORY" \
-      '[.stories[]? | select(.id == $s and .status != "done" and ((.links // []) | map(select(.method == "explicit_tag")) | length) == 0)] | length' \
+  # `|| true` guards the whole pipe under `set -o pipefail`: a state.yaml
+  # with no active_story line makes grep exit 1, which would otherwise kill
+  # this script outright (no WARNING, no summary line) instead of falling
+  # through to the empty-ACTIVE_STORY branch below.
+  ACTIVE_STORY="$(grep '^active_story:' specs/state.yaml 2>/dev/null | awk '{print $2}' || true)"
+  if [[ -z "$ACTIVE_STORY" ]]; then
+    classify WARNING "specs/state.yaml has no active_story set — zero-tag check skipped, not a pass"
+  else
+    STORY_EXISTS="$(jq --arg s "$ACTIVE_STORY" \
+      '[.stories[]? | select(.id == $s)] | length' \
       specs/traceability-matrix.json 2>/dev/null || echo 0)"
-    (( UNDONE > 0 )) && classify BLOCKER "active story $ACTIVE_STORY has zero explicit story-tag links"
+    if [[ "$STORY_EXISTS" -eq 0 ]]; then
+      classify WARNING "active_story $ACTIVE_STORY not found in specs/traceability-matrix.json — zero-tag check skipped, not a pass"
+    else
+      UNDONE="$(jq --arg s "$ACTIVE_STORY" \
+        '[.stories[]? | select(.id == $s and .status != "done" and ((.links // []) | map(select(.method == "explicit_tag")) | length) == 0)] | length' \
+        specs/traceability-matrix.json 2>/dev/null || echo 0)"
+      (( UNDONE > 0 )) && classify BLOCKER "active story $ACTIVE_STORY has zero explicit story-tag links"
+    fi
   fi
   COVERAGE="$(jq -r '.summary.coverage_percent // .coverage_percent // empty' specs/traceability-matrix.json 2>/dev/null)"
   if [[ -n "$COVERAGE" && "$COVERAGE" != "null" ]]; then

package/scripts/test-completeness-critic-scope.sh

@@ -0,0 +1,99 @@
+#!/usr/bin/env bash
+# story: e53s01
+# test-completeness-critic-scope.sh — regression test for
+# BUG-2026-07-23-completeness-critic-code-tags-schema-drift: the zero-tag
+# check must scope to the active story only (not siblings/other epics), and
+# must WARN — not silently no-op — when active_story is unset or unresolved.
+#
+# Usage: bash scripts/test-completeness-critic-scope.sh
+
+set -euo pipefail
+REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+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)); }
+
+STATE_FILE="specs/state.yaml"
+MATRIX_FILE="specs/traceability-matrix.json"
+STATE_BACKUP=$(mktemp)
+MATRIX_BACKUP=$(mktemp)
+cp "$STATE_FILE" "$STATE_BACKUP"
+cp "$MATRIX_FILE" "$MATRIX_BACKUP"
+
+cleanup() {
+  cp "$STATE_BACKUP" "$STATE_FILE"
+  cp "$MATRIX_BACKUP" "$MATRIX_FILE"
+  rm -f "$STATE_BACKUP" "$MATRIX_BACKUP"
+}
+trap cleanup EXIT
+
+run_critic() {
+  bash scripts/lib/completeness-critic.sh 2>&1 || true
+}
+
+# Fixture matrix: one untagged sibling story (e00s02) that must NOT block,
+# and the active story (e00s01) which is under test.
+write_matrix() {
+  local active_links="$1"
+  cat > "$MATRIX_FILE" <<FIXTUREEOF
+{
+  "stories": [
+    {"id": "e00s01", "status": "in_progress", "links": ${active_links}},
+    {"id": "e00s02", "status": "todo", "links": []}
+  ]
+}
+FIXTUREEOF
+}
+
+# --- Scenario: active_story unset → WARNING, not silent pass ---
+sed -i.bak '/^active_story:/d' "$STATE_FILE" && rm -f "${STATE_FILE}.bak"
+write_matrix '[]'
+output=$(run_critic)
+if echo "$output" | grep -q "\[WARNING\].*no active_story set"; then
+  tt_pass "unset active_story produces an explicit WARNING"
+else
+  tt_fail "unset active_story did not produce the expected WARNING"
+fi
+
+# --- Scenario: active_story set but absent from the matrix → WARNING ---
+printf 'active_story: e99s99\n' >> "$STATE_FILE"
+output=$(run_critic)
+if echo "$output" | grep -q "\[WARNING\].*e99s99 not found"; then
+  tt_pass "unresolved active_story produces an explicit WARNING"
+else
+  tt_fail "unresolved active_story did not produce the expected WARNING"
+fi
+sed -i.bak '/^active_story:/d' "$STATE_FILE" && rm -f "${STATE_FILE}.bak"
+
+# --- Scenario: active story has zero explicit_tag links → BLOCKER, scoped to it ---
+printf 'active_story: e00s01\n' >> "$STATE_FILE"
+write_matrix '[]'
+output=$(run_critic)
+if echo "$output" | grep -q "\[BLOCKER\] active story e00s01 has zero explicit story-tag links"; then
+  tt_pass "active story with zero tags is correctly flagged as BLOCKER"
+else
+  tt_fail "active story with zero tags was not flagged as BLOCKER"
+fi
+
+# --- Scenario: active story IS tagged → no BLOCKER, even though sibling e00s02 is untagged ---
+write_matrix '[{"method": "explicit_tag", "file": "scripts/fixture.sh", "line": 1, "confidence": 1.0}]'
+output=$(run_critic)
+if echo "$output" | grep -q "\[BLOCKER\] active story e00s01"; then
+  tt_fail "tagged active story incorrectly flagged as BLOCKER"
+else
+  tt_pass "tagged active story is not flagged, and untagged sibling e00s02 does not leak into the check"
+fi
+
+echo "---"
+if [[ "$FAILURES" -eq 0 ]]; then
+  echo -e "${GREEN}test-completeness-critic-scope: ALL PASS${NC}"
+else
+  echo -e "${RED}test-completeness-critic-scope: $FAILURES failure(s)${NC}"
+fi
+exit "$FAILURES"

package/scripts/test-generate-epics-wiki-zero-stories.sh

@@ -0,0 +1,64 @@
+#!/usr/bin/env bash
+# story: e53s01
+# test-generate-epics-wiki-zero-stories.sh — regression test for
+# BUG-2026-07-23-epics-wiki-empty-references: generate-epics-wiki.sh must
+# skip epics with zero sliced stories rather than emit an invalid OKF bundle
+# with an empty references[].
+#
+# Usage: bash scripts/test-generate-epics-wiki-zero-stories.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)); }
+
+FIXTURE_ID="e00"
+FIXTURE_DIR="specs/epics/e00-zero-story-fixture"
+FIXTURE_BUNDLE="specs/epics-wiki/${FIXTURE_ID}.okf.md"
+
+cleanup() {
+  rm -rf "$FIXTURE_DIR"
+  rm -f "$FIXTURE_BUNDLE"
+}
+trap cleanup EXIT
+
+mkdir -p "$FIXTURE_DIR"
+cat > "${FIXTURE_DIR}/epic.yaml" <<'FIXTUREEOF'
+id: e00
+title: "Zero-story fixture epic"
+wsjf: 0
+bcps: 0
+capsule_dir: epics/e00-zero-story-fixture
+mode: capsule
+status: todo
+depends_on: []
+stories: []
+FIXTUREEOF
+
+# A scoped-but-unsliced epic has a `stories:` key with nothing under it —
+# grep -c '^\s*- id:' correctly returns 0 for this shape.
+[[ -f "$FIXTURE_BUNDLE" ]] && rm -f "$FIXTURE_BUNDLE"
+
+bash scripts/generate-epics-wiki.sh > /dev/null
+
+if [[ ! -f "$FIXTURE_BUNDLE" ]]; then
+  tt_pass "generate-epics-wiki.sh skips a zero-story epic (no bundle emitted)"
+else
+  tt_fail "generate-epics-wiki.sh emitted a bundle for a zero-story epic: $FIXTURE_BUNDLE"
+fi
+
+echo "---"
+if [[ "$FAILURES" -eq 0 ]]; then
+  echo -e "${GREEN}test-generate-epics-wiki-zero-stories: ALL PASS${NC}"
+else
+  echo -e "${RED}test-generate-epics-wiki-zero-stories: $FAILURES failure(s)${NC}"
+fi
+exit "$FAILURES"

package/scripts/test-golden-g11-worktree-venv.sh

@@ -0,0 +1,63 @@
+#!/usr/bin/env bash
+# story: e53s01
+# test-golden-g11-worktree-venv.sh — regression test for
+# BUG-2026-07-23-golden-g11-worktree-venv: golden-g11-gitignore-venv.sh must
+# PASS in a fresh worktree where .venv does not exist yet on disk (before
+# setup-environment has run), not just when a real .venv is already present.
+#
+# Usage: bash scripts/test-golden-g11-worktree-venv.sh
+
+set -euo pipefail
+REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+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'; }
+
+VENV_MOVED=0
+if [[ -e .venv ]]; then
+  mv .venv .venv.test-golden-g11-backup
+  VENV_MOVED=1
+fi
+
+cleanup() {
+  rm -rf .venv
+  if [[ "$VENV_MOVED" -eq 1 ]]; then
+    mv .venv.test-golden-g11-backup .venv
+  fi
+}
+trap cleanup EXIT
+
+# --- Scenario: .venv absent (fresh worktree) → gate still PASSes ---
+if [[ -e .venv ]]; then
+  tt_fail "test setup failed to remove .venv before running the gate"
+else
+  output=$(bash scripts/golden-g11-gitignore-venv.sh 2>&1 | strip_ansi) && exit_code=0 || exit_code=$?
+  if [[ "$exit_code" -eq 0 ]] && echo "$output" | grep -q "PASS git check-ignore .venv"; then
+    tt_pass "gate PASSes when .venv does not exist on disk"
+  else
+    tt_fail "gate did not PASS with .venv absent (exit=$exit_code)"
+  fi
+
+  # The gate must clean up the .venv it created for the check — a fresh
+  # worktree shouldn't be left with a stray directory after a gate run.
+  if [[ ! -e .venv ]]; then
+    tt_pass "gate removes the .venv it created for the check"
+  else
+    tt_fail "gate left a stray .venv behind after the check"
+  fi
+fi
+
+echo "---"
+if [[ "$FAILURES" -eq 0 ]]; then
+  echo -e "${GREEN}test-golden-g11-worktree-venv: ALL PASS${NC}"
+else
+  echo -e "${RED}test-golden-g11-worktree-venv: $FAILURES failure(s)${NC}"
+fi
+exit "$FAILURES"

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,100 @@
+#!/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=$(jq -r '.version' package.json 2>/dev/null)
+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"
+
+# Values flow through the environment, never interpolated into the python
+# source string — string-interpolating shell variables into `python3 -c`
+# turns any unvalidated field (e.g. CURRENT_VERSION, sourced from
+# package.json) into a code-injection vector.
+TOMBSTONE_FILE="$TOMBSTONES_FILE" \
+TOMBSTONE_OLD_NAME="$OLD_NAME" \
+TOMBSTONE_NEW_NAME="$NEW_NAME" \
+TOMBSTONE_CREATED_AT="$CREATED_AT" \
+TOMBSTONE_VERSION="$CURRENT_VERSION" \
+python3 -c "
+import os
+import yaml
+path = os.environ['TOMBSTONE_FILE']
+d = yaml.safe_load(open(path)) or {'tombstones': []}
+d.setdefault('tombstones', []).append({
+    'old_name': os.environ['TOMBSTONE_OLD_NAME'],
+    'new_name_or_merge_target': os.environ['TOMBSTONE_NEW_NAME'],
+    'created_at': os.environ['TOMBSTONE_CREATED_AT'],
+    'created_at_version': os.environ['TOMBSTONE_VERSION'],
+})
+yaml.dump(d, open(path, 'w'), default_flow_style=False)
+"
+
+echo "Tombstoned: ${OLD_NAME} -> ${NEW_NAME}"
+echo "Registered in ${TOMBSTONES_FILE}"

package/scripts/validate-tombstones.sh

@@ -0,0 +1,82 @@
+#!/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"
+NAME_PATTERN='^[a-z][a-z0-9-]*$'
+FAIL=0
+
+if [[ ! -f "$TOMBSTONES_FILE" ]]; then
+  echo -e "${GREEN}OK${NC}: no tombstones registered"
+  exit 0
+fi
+
+CURRENT_VERSION=$(jq -r '.version' package.json 2>/dev/null)
+
+# A "release" for tombstone-expiry purposes is a minor/major version bump.
+# This repo ships via semantic-release on every merge to main (multiple
+# patch releases per day) — comparing full semver strings would expire
+# every tombstone within minutes instead of giving consumers the one-release
+# migration window CONVENTIONS.md promises.
+release_train() { echo "$1" | cut -d. -f1-2; }
+
+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
+
+  # Threat-model mitigation (specs/security/epics/e53/THREAT_MODEL.md): apply
+  # the same kebab-case validation tombstone-skill.sh applies before writing
+  # entries, since these names come back out of specs/tombstones.yaml here
+  # and are used to construct a filesystem path.
+  if [[ ! "$old_name" =~ $NAME_PATTERN || ! "$new_name" =~ $NAME_PATTERN ]]; then
+    echo -e "${RED}FAIL${NC}: '${old_name}' -> '${new_name}' — not a valid skill name (must match ${NAME_PATTERN})"
+    FAIL=1
+    continue
+  fi
+
+  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" && "$(release_train "$created_version")" != "$(release_train "$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"