staleness-gate

Staleness Gate Skill

Ensures the codemunch index is fresh before any query runs. This skill is called automatically — users never invoke it directly.

Decision flow

1. Does .claude/codemunch/index.json exist?
   NO  → First-run: run detect-lsp skill, then full index skill → done
   YES → Continue to step 2

2. Get index timestamp from index.json "generated" field

3. Find files changed since index was built:
   git diff --name-only --diff-filter=ACMRD $(git log -1 --format=%H --before="$GENERATED_TIMESTAMP") HEAD

   Also check for untracked source files:
   git ls-files --others --exclude-standard

4. Filter to source files only (exclude non-code files like .md, .txt, images, etc.)

5. Are there changed source files?
   NO  → Index is fresh, proceed with query
   YES → Run incremental re-index (step 6)

6. Incremental re-index:
   - For each changed/added file: re-extract symbols using the best available engine
   - For each deleted file: remove its symbols from the index
   - Update the "generated" timestamp
   - Update the "file_hashes" manifest
   - Report: "Auto-updated index: +N symbols, -M symbols, K files re-indexed"

Step 1 — Check index exists

# Check for index
if [ -f .claude/codemunch/index.json ]; then
  echo "INDEX_EXISTS"
else
  echo "NO_INDEX"
fi

If NO_INDEX:

1. Check if .claude/codemunch/config.json exists — if not, run the detect-lsp skill first
2. Run the index skill with full mode
3. Report: "First-run: auto-built codemunch index (N symbols across M files)"
4. Continue with the original query

Step 2 — Get index timestamp

# Extract the generated timestamp from index
python3 -c "
import json
with open('.claude/codemunch/index.json') as f:
    idx = json.load(f)
print(idx.get('generated', ''))
" 2>/dev/null || jq -r '.generated' .claude/codemunch/index.json

Step 3 — Find changed files since index was built

GENERATED="2026-03-11T02:14:00Z"

# Find the commit closest to when the index was built
BASE_COMMIT=$(git log -1 --format=%H --before="$GENERATED" 2>/dev/null)

if [ -z "$BASE_COMMIT" ]; then
  # No commit found before timestamp — index predates all commits, do full re-index
  echo "FULL_REINDEX_NEEDED"
else
  # Get changed files since that commit
  git diff --name-only --diff-filter=ACMRD "$BASE_COMMIT" HEAD 2>/dev/null
fi

# Also check untracked files (new files not yet committed)
git ls-files --others --exclude-standard 2>/dev/null