refresh-context-map

refresh-context-map

Rebuild the smart-context-surface manifest used by the PreToolUse hook (scripts/hooks/context-surface.sh). See docs/adr/0008-smart-context-surfacing-via-pretooluse-hook.md for the design rationale.

When to invoke

• After adding / moving / deleting AIDEV-NOTE / AIDEV-TODO / AIDEV-QUESTION anchors.
• After adding / removing per-directory AGENTS.md files.
• After adding new ADRs in docs/adr/ that reference specific source files.
• After a git merge that touched anchor-bearing files (.gitattributes keeps the local manifest on conflict via merge=ours, but it'll be stale relative to the merged tree until rebuilt).
• When /stack-check flags drift between the manifest and git ls-files.
• Once per significant refactor that moved a lot of files.

When NOT to invoke

• On every commit — opt-in pre-commit hook (.githooks/) does it automatically if enabled. If you've enabled it, manual /refresh-context-map is redundant.
• When you have not adopted the smart-context-surfacing stack in this repo (no .claude-leverage-context-map.json present means the PreToolUse hook silently no-ops — nothing to refresh).

What it does

Runs:

python ${CLAUDE_PLUGIN_ROOT}/scripts/build-context-map.py

from the repo root. The script:

1. Walks every git-tracked file (via git ls-files), skipping binaries (NUL-byte sniff).
2. For each file with AIDEV-* anchors, indexes:
   • Anchors inside the file
   • Anchors in sibling files (same directory)
   • The chain of AGENTS.md from dirname(file) to repo root
   • ADR files (docs/adr/*.md) that mention this file path verbatim (word-boundary match)
3. Writes .claude-leverage-context-map.json at the repo root, atomically (.tmp + rename).

The PreToolUse hook reads this manifest on every Read/Edit/Write/MultiEdit and injects a per-file context slice via hookSpecificOutput.additionalContext.

Hard rules

• Never hand-edit .claude-leverage-context-map.json. It's generated. Edit the source (anchors, per-dir AGENTS.md, ADRs) and rebuild. A hand-edited manifest drifts from the tree, and the next rebuild silently overwrites it.
• The manifest IS committed — it is not gitignored. Unusual for a generated artifact, but deliberate: every clone and every session gets a fresh-enough copy with no build step. .gitattributes sets merge=ours so merge conflicts on it auto-resolve to local — rebuild afterward (see "When to invoke").
• Read-only on source. This skill only ever writes the manifest; it never touches the files it indexes.

If the rebuild fails

A failed rebuild is safe. If python is missing or the script errors, the manifest is simply not updated — the PreToolUse hook then reads a stale (or absent) manifest and no-ops gracefully, surfacing slightly less context. It never blocks a tool call. So a failed rebuild degrades the feature; it does not break your session. Fix the Python environment and re-run when convenient.

Verifying the rebuild

After running, the script prints a summary line:

Wrote ./.claude-leverage-context-map.json (234 files, 89 anchors)

Higher numbers than last time → you've added anchors / ADR references. Lower numbers → anchors were deleted or files removed from git ls-files.

To check drift without writing (CI use):

python scripts/build-context-map.py --check
# exit 0 if up to date, exit 1 with "DRIFT:" line on stderr if regen would differ

Opting out per-session

Set CLAUDE_LEVERAGE_CTX_DISABLE=1 in the environment to disable the hook entirely without removing the manifest. Useful for one-off diagnostic sessions where the context injection is noise.

Verbose mode

By default the hook surfaces only AIDEV-* anchors (the trap-catching content per the Run-3 token-tax finding). Set CLAUDE_LEVERAGE_CTX_VERBOSE=1 to also include per-dir AGENTS.md references and related ADR paths in every injection. Useful in repos where the per-dir AGENTS.md surface is dense and worth the extra tokens; off by default to keep the tax minimal in the common case.