docs-spec-inventory-stale-stub

Answer

Root cause: specs/README.md was a hand-maintained stub ("No specs have been created") while the filesystem held 29 spec files. Nothing regenerated the index, so it drifted from reality — a dead index that AGENTS.md pointed agents at.

Fix — two scripts:

1. regenerate_spec_inventory.sh — rebuilds specs/README.md purely from the filesystem. Inventory = ls specs/*.md (minus README itself); description = first H1 line of each spec:

#!/usr/bin/env bash
set -euo pipefail
SPECS_DIR="${1:-specs}"
README="$SPECS_DIR/README.md"

# 1. Inventory = every markdown file in specs/ except README.md.
#    LC_ALL=C makes sorting byte-order deterministic across environments.
mapfile -t files < <(
  LC_ALL=C ls "$SPECS_DIR"/*.md \
    | sed 's#^'"$SPECS_DIR"'/##' \
    | grep -v '^README\.md$' \
    | LC_ALL=C sort
)

# 2. Description = first H1 ("# ...") line; fallback if missing.
title_of() {
  grep -m1 '^# ' "$SPECS_DIR/$1" | sed 's/^# //' || echo "(no H1 title)"
}

# 3. Emit the README (header + table + count).
{
  echo "# Specs"
  echo
  echo "Inventory of all specifications. Regenerated by \`regenerate_spec_inventory.sh\` — do not edit by hand."
  echo
  echo "| Spec | Description |"
  echo "| --- | --- |"
  for f in "${files[@]}"; do
    printf '| [%s](%s) | %s |\n' "$f" "$f" "$(title_of "$f")"
  done
  echo
  echo "Total: ${#files[@]} specs."
} > "$README"

2. verify_spec_inventory.sh — CI-style gate: count + link resolution via comm on normalized filename lists (strip specs/ prefix, LC_ALL=C sort both sides), then assert no stale stub text:

#!/usr/bin/env bash
set -euo pipefail
SPECS_DIR="${1:-specs}"
README="$SPECS_DIR/README.md"
fail() { echo "FAIL: $*" >&2; exit 1; }

# Expected: files on disk, stripped of prefix, sorted.
LC_ALL=C ls "$SPECS_DIR"/*.md \
  | sed 's#^'"$SPECS_DIR"'/##' \
  | grep -v '^README\.md$' \
  | LC_ALL=C sort > /tmp/expected.txt

# Indexed: relative link targets in the README, sorted.
grep -oE '\[[^]]*\]\([^)#][^)]*\)' "$README" \
  | sed -E 's/^\[[^]]*\]\(([^)]*)\)$/\1/' \
  | LC_ALL=C sort > /tmp/indexed.txt

# comm -3: lines unique to either side = drift -> fail.
if [ -s "$(comm -3 /tmp/expected.txt /tmp/indexed.txt > /tmp/diff.txt; echo /tmp/diff.txt)" ]; then
  cat /tmp/diff.txt >&2; exit 1
fi

# Every indexed link must resolve to a real file.
while read -r f; do
  [ -f "$SPECS_DIR/$f" ] || fail "dangling link: $f"
done < /tmp/indexed.txt

# No stale stub text.
grep -qi 'no specs have been created\|under construction' "$README" && fail "stale stub text"

echo "PASS: $(wc -l < /tmp/indexed.txt)/$(wc -l < /tmp/expected.txt) links resolve."

Resulting README row format: | [auth.md](auth.md) | Authentication & Session Management | with Total: 29 specs. at the bottom.