kb-staleness-check

Knowledge Base Staleness Check

Verify that the knowledge base shelf-index reflects the current state of the library files. Reports drifted entries without making changes. Designed as the touch-point between the knowledge base plugin and existing SDLC validation operations.

This is the opt-in environment validation extension described in the EPIC. The plugin does not modify the existing validate skill in sdlc-core directly — instead, this skill is shipped as a standalone check that users can invoke manually or wire into their pre-push validation when they want it.

Argument

• (no argument) — warning mode (default). Reports stale entries; exits 0 regardless. Informational only.
• --strict — strict mode. Reports stale entries and exits 1 if any drift is found. Use this when wired into pre-push hooks where stale indexes should block the push.

Preflight

• Verify the knowledge base is configured (the [Knowledge Base] section exists in CLAUDE.md).
• Verify the shelf-index file exists at the configured path.
• If neither exists, exit 0 silently with a single-line note: "No knowledge base configured; skipping staleness check." This makes the skill safe to wire into pre-push hooks unconditionally — projects without a knowledge base see no impact.

Steps

1. Read the configured paths

Parse the [Knowledge Base] section from CLAUDE.md for:

• library_path (default library/)
• shelf_index_path (default library/_shelf-index.md)

2. Compute current hashes

Use the same logic as kb-rebuild-indexes:

find <library_path> -name "*.md" \
  ! -name "_shelf-index.md" \
  ! -name "_index.md" \
  ! -name "log.md" \
  ! -path "<library_path>/raw/*" \
  -exec sha256sum {} \;

Build {file_path → current_hash}.

3. Read recorded hashes from the shelf-index

Parse the shelf-index, extracting each entry's **Hash:** field. Build {file_path → recorded_hash}.

4. Compare and classify

For each file: