/refresh-context-map

name: refresh-context-map
description: USE WHEN AIDEV anchors / per-dir AGENTS.md / ADRs have changed in this repo and the smart-context-surfacing PreToolUse hook needs an updated manifest. Rebuilds `.claude-leverage-context-map.json` at the repo root by running `scripts/build-context-map.py`. Read-only on source — only writes the manifest.

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`](../../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.