refine(codemap): rename skills scan-codebase, query-code & fix Win CI

- Rename /codemap:scan → /codemap:scan-codebase and /codemap:query → /codemap:query-code to eliminate routing ambiguity with generic names
- Propagate new names across integration/SKILL.md (8 refs), calibrate/modes/skills.md, preflight-helpers.md, develop/skills/review, oss/skills/review, develop/README.md, codemap/README.md (section headings, TOC, anchors, examples)
- Update bin/ scripts (scan-stats, check_index_freshness, check_injection, scan-query, codemap-resolve) and their tests
- codemap 0.4.2 → 0.5.0 (X-class: user-visible invocation rename); foundry 0.22.1 → 0.22.2 (Y-class: haiku rule addition from prior session)

---
Co-authored-by: Claude Code <noreply@anthropic.com>

Author: Borda

plugins/codemap/.claude-plugin/plugin.json

@@ -17,5 +17,5 @@
   "license": "MIT",
   "name": "codemap",
   "repository": "https://github.com/Borda/AI-Rig",
-  "version": "0.4.2"
+  "version": "0.5.0"
 }

plugins/codemap/README.md

@@ -20,8 +20,8 @@ ______________________________________________________________________
 - [Quick start](#quick-start)
 - [Skills reference](#skills-reference)
   - [integration](#integration)
-  - [scan](#scan)
-  - [query](#query)
+  - [scan-codebase](#scan-codebase)
+  - [query-code](#query-code)
 - [How it works](#how-it-works)
 - [Configuration](#configuration)
 - [Troubleshooting](#troubleshooting)
@@ -87,7 +87,7 @@ Zero codemap timeouts. Plain-arm agents hit the 300-second hard timeout on sever
 >
 > codemap injects a rich dependency graph into every agent prompt. On weaker models or tasks with large blast-radius graphs, this extra context can overwhelm the model and cause it to fall back to grep-heavy loops — performing *worse* than plain arm. The benchmark labels this failure mode `degenerate_grep_loop`.
 >
-> Good integration requires three things: (1) **skill-first protocol** — the agent calls `/codemap:query` before any Grep/Glob; (2) **bounded call budget** — max 3 codemap queries per task; (3) **hard stop on `exhaustive: true`** — when the index says the list is complete, write the answer immediately, no more tool calls. Skipping any of these — especially ignoring the exhaustive flag — is the primary cause of regressions that flip the codemap benefit into a liability. Use `/codemap:integration init` to wire integration correctly rather than injecting context manually.
+> Good integration requires three things: (1) **skill-first protocol** — the agent calls `/codemap:query-code` before any Grep/Glob; (2) **bounded call budget** — max 3 codemap queries per task; (3) **hard stop on `exhaustive: true`** — when the index says the list is complete, write the answer immediately, no more tool calls. Skipping any of these — especially ignoring the exhaustive flag — is the primary cause of regressions that flip the codemap benefit into a liability. Use `/codemap:integration init` to wire integration correctly rather than injecting context manually.
 
 ______________________________________________________________________
 
@@ -157,7 +157,7 @@ Two commands — then forget about codemap and just use your normal skills.
 **Step 1 — build the index:**
 
 ```text
-/codemap:scan
+/codemap:scan-codebase
 ```
 
 Output:
@@ -196,7 +196,7 @@ That is it. Now run your normal skills — codemap works silently in the backgro
 /oss:review                  # reviewer gets structural context on changed modules
 ```
 
-If you ever want to explore structure manually, `/codemap:query` is there for you — but most users rarely need it.
+If you ever want to explore structure manually, `/codemap:query-code` is there for you — but most users rarely need it.
 
 ______________________________________________________________________
 
@@ -230,7 +230,7 @@ Each check prints `✓`, `✗`, or `⚠` with a one-line remediation hint if nee
 
 Interactive onboarding for the current project:
 
-1. Builds the index if it is missing (offers to run `/codemap:scan`)
+1. Builds the index if it is missing (offers to run `/codemap:scan-codebase`)
 2. Discovers all installed skills and agents across all plugins
 3. Scores candidates by value tier (High / Medium / Low / Skip) based on whether structural context would help them
 4. Presents a recommendation table and asks which to wire in
@@ -275,9 +275,9 @@ run `scan-query central --top 5` (and `scan-query rdeps <target_module>` when a
 **before** any Glob/Grep exploration for structural information. Skip silently if the index is absent.
 ```
 
-### scan
+### scan-codebase
 
-**Trigger**: `/codemap:scan`
+**Trigger**: `/codemap:scan-codebase`
 
 Builds the structural index by running `ast.parse` across every `.py` file in the project. Writes the index to `.cache/scan/<project>.json`. Reports how many modules were indexed, how many were degraded (parse errors), and which five modules have the highest blast radius.
 
@@ -303,28 +303,28 @@ Run a full scan once when you first set up the project. After that, `--increment
 #### Example
 
 ```text
-/codemap:scan
+/codemap:scan-codebase
 ```
 
 ```text
-/codemap:scan --incremental
+/codemap:scan-codebase --incremental
 ```
 
 ______________________________________________________________________
 
-<a id="query"></a>
+<a id="query-code"></a>
 
 <details>
 
 <summary>
 
-### query — full subcommand reference
+### query-code — full subcommand reference
 
 </summary>
 
-### query
+### query-code
 
-**Trigger**: `/codemap:query <subcommand> [args]`
+**Trigger**: `/codemap:query-code <subcommand> [args]`
 
 **Auto-invokes when:** user asks about module relationships, dependency graph, callers/callees, or blast radius; phrases: "what depends on", "who calls", "imports of", "blast radius of". Requires codemap index to exist (skill self-checks and no-ops gracefully if absent).
 
@@ -357,7 +357,7 @@ Retrieve function or class source by name instead of reading the full file — d
 
 #### Function-level call graph queries (v3 index)
 
-These require a v3 index built by `/codemap:scan`. If your index is older (v2), the commands return a clear upgrade message.
+These require a v3 index built by `/codemap:scan-codebase`. If your index is older (v2), the commands return a clear upgrade message.
 
 | Subcommand             | What it answers                                        |
 | ---------------------- | ------------------------------------------------------ |
@@ -382,28 +382,28 @@ Use `module::function` format for qualified names, for example `mypackage.auth::
 
 ```text
 # Before refactoring auth.py — understand full blast radius
-/codemap:query rdeps myproject.auth
+/codemap:query-code rdeps myproject.auth
 
 # Before adding a dependency to models.py — see what already imports it
-/codemap:query central --top 5
+/codemap:query-code central --top 5
 
 # Check if api and db are already coupled before adding a direct import
-/codemap:query path myproject.api myproject.db
+/codemap:query-code path myproject.api myproject.db
 
 # Read just the validate_token function without loading the whole file
-/codemap:query symbol validate_token
+/codemap:query-code symbol validate_token
 
 # Find all functions whose name starts with "validate" (unlimited results)
-/codemap:query find-symbol "^validate" --limit 0
+/codemap:query-code find-symbol "^validate" --limit 0
 
 # Check transitive impact of changing fetch_user at the function level
-/codemap:query fn-blast myproject.db::fetch_user
+/codemap:query-code fn-blast myproject.db::fetch_user
 
 # Exclude test modules from blast-radius analysis
-/codemap:query central --exclude-tests --top 10
+/codemap:query-code central --exclude-tests --top 10
 
 # Query a specific index file (monorepo with multiple projects)
-/codemap:query central --index /path/to/.cache/scan/subproject.json
+/codemap:query-code central --index /path/to/.cache/scan/subproject.json
 ```
 
 </details>
@@ -473,7 +473,7 @@ The index is always written to `.cache/scan/<project>.json` at the project root.
 If your Python source is not at the git root, pass `--root`:
 
 ```text
-/codemap:scan --root src/mypackage
+/codemap:scan-codebase --root src/mypackage
 ```
 
 Or from the terminal:
@@ -505,21 +505,21 @@ ______________________________________________________________________
 The index has not been built for this project yet. Run:
 
 ```text
-/codemap:scan
+/codemap:scan-codebase
 ```
 
 ### Stale index warning
 
 `scan-query` detected that Python files were committed after the index was built. Run an incremental rebuild:
 
 ```text
-/codemap:scan --incremental
+/codemap:scan-codebase --incremental
 ```
 
 Or a full rebuild if you have made large structural changes:
 
 ```text
-/codemap:scan
+/codemap:scan-codebase
 ```
 
 ### scan-query not found in the terminal
@@ -562,7 +562,7 @@ Generated files (e.g. protobuf output) are expected to degrade. They are not par
 The function-level call graph queries (`fn-deps`, `fn-rdeps`, `fn-central`, `fn-blast`) require a v3 index. Your current index is older. Rebuild:
 
 ```text
-/codemap:scan
+/codemap:scan-codebase
 ```
 
 ### The develop plugin does not seem to use codemap

plugins/codemap/bin/check_index_freshness.py

@@ -132,13 +132,13 @@ def format_status(scanned_at: str | None, scan_time: datetime | None, now: datet
     """
     if scan_time is None:
         if not scanned_at:
-            return "⚠ freshness: scanned_at missing — index may be corrupted\n  → Re-run /codemap:scan\n"
-        return f"⚠ freshness: could not parse scanned_at timestamp ({scanned_at}) — run /codemap:scan\n"
+            return "⚠ freshness: scanned_at missing — index may be corrupted\n  → Re-run /codemap:scan-codebase\n"
+        return f"⚠ freshness: could not parse scanned_at timestamp ({scanned_at}) — run /codemap:scan-codebase\n"
 
     days = age_days(scan_time, now)
     scan_date = (scanned_at or "")[:10]
     if days > STALE_THRESHOLD_DAYS:
-        return f"⚠ freshness: {days} day(s) ago ({scan_date})\n  → Run /codemap:scan to refresh\n"
+        return f"⚠ freshness: {days} day(s) ago ({scan_date})\n  → Run /codemap:scan-codebase to refresh\n"
     return f"✓ freshness: {days} day(s) ago ({scan_date})\n"
 
 

plugins/codemap/bin/check_injection.py

@@ -103,7 +103,7 @@ def resolve_plugin_root(explicit: str | None) -> Path | None:
         if _is_plausible_plugin_dir(candidate):
             return candidate
         # Reject silently → fall through to auto-discovery (preserves prior UX for missing paths).
-    home = Path(os.path.expanduser("~"))
+    home = Path(os.environ.get("HOME") or os.path.expanduser("~"))
     candidates = sorted(
         home.joinpath(".claude/plugins/cache").glob(DEFAULT_CACHE_GLOB),
         key=lambda p: p.stat().st_mtime if p.exists() else 0.0,
@@ -231,7 +231,7 @@ def build_audit_lines(cache: Path) -> list[str]:
             "",
             "--- check complete ---",
             "If any check failed:",
-            "  • /codemap:scan    — build or refresh the index",
+            "  • /codemap:scan-codebase    — build or refresh the index",
             "  • /codemap:integration init — add injection to more skills/agents",
             "  • /codemap:integration check — re-run after fixes",
         ]

plugins/codemap/bin/scan-query

@@ -145,7 +145,7 @@ def load_index(path: Path) -> dict:
         path: filesystem path to the index JSON file.
     """
     if not path.exists():
-        _exit_error(f"Index not found at {path}. Run /codemap:scan first.")
+        _exit_error(f"Index not found at {path}. Run /codemap:scan-codebase first.")
     with path.open() as f:
         return json.load(f)
 
@@ -239,15 +239,15 @@ def warn_if_stale(index: dict) -> None:
                 n = len(stale_files)
                 print(
                     f"⚠ codemap index stale — {n} file(s) changed since last scan."
-                    " Run /codemap:scan --incremental to update.",
+                    " Run /codemap:scan-codebase --incremental to update.",
                     file=sys.stderr,
                 )
             return
     # v2 index fallback: timestamp-based check
     scanned_at = index.get("scanned_at", "")
     if scanned_at and check_staleness(scanned_at):
         print(
-            "⚠ codemap index may be stale — Python files changed since last scan. Re-run /codemap:scan.",
+            "⚠ codemap index may be stale — Python files changed since last scan. Re-run /codemap:scan-codebase.",
             file=sys.stderr,
         )
 
@@ -351,7 +351,7 @@ def _require_call_graph(index: dict) -> None:
         index: parsed codemap index dict to check for v3 call graph support.
     """
     if not _has_call_graph(index):
-        _exit_error("Index is v2 — call graph not available. Re-run /codemap:scan to upgrade.")
+        _exit_error("Index is v2 — call graph not available. Re-run /codemap:scan-codebase to upgrade.")
 
 
 def _current_git_sha() -> str | None:
@@ -406,7 +406,7 @@ def _coverage(index: dict) -> dict:
         note = (
             f"All {total} indexed modules were searched. "
             "⚠ Index may be stale — source files changed since last scan. "
-            "Re-run /codemap:scan to update before relying on this result."
+            "Re-run /codemap:scan-codebase to update before relying on this result."
         )
         exhaustive = False
     else:
@@ -613,7 +613,7 @@ def cmd_symbol(index: dict, name: str, limit: int = 20, exclude_tests: bool = Fa
                     matches.append((m, sym))
 
     if not matches:
-        _exit_error(f"Symbol '{name}' not found. Try /codemap:query find-symbol <pattern> to search.")
+        _exit_error(f"Symbol '{name}' not found. Try /codemap:query-code find-symbol <pattern> to search.")
 
     if limit > 0:
         matches = matches[:limit]

plugins/codemap/bin/scan-stats.py

@@ -47,7 +47,7 @@ def _load_index(root: str) -> dict:
     try:
         size = os.path.getsize(index_path)
     except FileNotFoundError:
-        print(f"Index not found: {index_path} — run /codemap:scan first")
+        print(f"Index not found: {index_path} — run /codemap:scan-codebase first")
         sys.exit(1)
     if size > MAX_INDEX_SIZE:
         print(f"Index too large ({size} bytes; max {MAX_INDEX_SIZE}): {index_path}")
@@ -56,7 +56,7 @@ def _load_index(root: str) -> dict:
         with open(index_path) as f:
             return json.load(f)
     except FileNotFoundError:
-        print(f"Index not found: {index_path} — run /codemap:scan first")
+        print(f"Index not found: {index_path} — run /codemap:scan-codebase first")
         sys.exit(1)
 
 

plugins/codemap/skills/integration/SKILL.md

@@ -14,7 +14,7 @@ Two modes: use `init` first-time to onboard, then `check` regularly to verify. D
 - **`check`** — fast diagnostic: finds `scan-query`, verifies index exists and fresh, runs smoke test, audits which skill files have injection block. Prints `✓`/`✗`/`⚠` per check with one-line remediation hints. Pure bash — no model reasoning needed for happy path.
 - **`init`** — interactive onboarding: builds index if missing, discovers all installed skills and agents, scores by how much codemap would help, presents recommendation table, asks which to wire in, inserts correct injection block into each selected file.
 
-NOT for: building or rebuilding index (use `/codemap:scan`); running structural query (use `/codemap:query`).
+NOT for: building or rebuilding index (use `/codemap:scan-codebase`); running structural query (use `/codemap:query-code`).
 
 Arguments: `check` (no args) or `init [--approve]` — `--approve` auto-applies all ★ recommendations non-interactively.
 
@@ -71,7 +71,7 @@ if [ "$C1_STATUS" = "failed" ]; then
 fi
 # PROJ/INDEX resolution — also used in Step I1 (init mode); keep in sync
 # NOTE: uses single-strategy basename lookup; scan-query uses three-strategy walk-up
-# If index not found here but scan-query works, run with explicit --index flag or re-run /codemap:scan from project root
+# If index not found here but scan-query works, run with explicit --index flag or re-run /codemap:scan-codebase from project root
 # bash 3.2 compatible — mapfile is bash 4+ only; macOS ships bash 3.2
 _idx=()
 while IFS= read -r line; do
@@ -87,7 +87,7 @@ if [ -f "$INDEX" ]; then
     printf "✓ index: exists\n"
 else
     printf "✗ index: not found\n"
-    printf "  → Run /codemap:scan to build the index\n"
+    printf "  → Run /codemap:scan-codebase to build the index\n"
     echo "failed" > "${TMPDIR:-/tmp}/codemap-c1-status"
     exit 1
 fi
@@ -124,11 +124,11 @@ AGE=$(echo "$SMOKE_RESULT" | jq -r '.age_hours')
 if [ "$OK" != "true" ]; then
     ERR=$(echo "$SMOKE_RESULT" | jq -r '.error // "unknown"')
     printf "✗ smoke test: %s\n" "$ERR"
-    printf "  → Re-run /codemap:scan to rebuild index\n"
+    printf "  → Re-run /codemap:scan-codebase to rebuild index\n"
 else
     printf "✓ smoke test: index valid (mtime-age=%sh)\n" "$AGE"
     if [ "$STALE" = "true" ]; then
-        printf "  ⚠ Index older than freshness threshold — run /codemap:scan to update\n"
+        printf "  ⚠ Index older than freshness threshold — run /codemap:scan-codebase to update\n"
     fi
 fi
 ```
@@ -170,14 +170,14 @@ Use `AskUserQuestion`:
 No codemap index found for project: $PROJ
 
 a) Build now ★ — scans all .py files via ast.parse (Python only), <60s on most projects
-b) Skip — I'll run /codemap:scan later (recommendations will be generic, no module-count weighting)
+b) Skip — I'll run /codemap:scan-codebase later (recommendations will be generic, no module-count weighting)
 ```
 
 If **a** (or auto-approved): verify binary exists first, then run scanner:
 
 ```bash
 # timeout: 5000
-[ -x "${CLAUDE_PLUGIN_ROOT:-plugins/codemap}/bin/scan-index" ] || { printf "✗ scan-index not found at ${CLAUDE_PLUGIN_ROOT:-plugins/codemap}/bin/scan-index\nTry: /codemap:scan to install and rebuild.\n"; exit 1; }
+[ -x "${CLAUDE_PLUGIN_ROOT:-plugins/codemap}/bin/scan-index" ] || { printf "✗ scan-index not found at ${CLAUDE_PLUGIN_ROOT:-plugins/codemap}/bin/scan-index\nTry: /codemap:scan-codebase to install and rebuild.\n"; exit 1; }
 # timeout: 360000
 ${CLAUDE_PLUGIN_ROOT:-plugins/codemap}/bin/scan-index
 ```
@@ -305,7 +305,7 @@ Use `AskUserQuestion`:
 Install post-commit git hook for automatic incremental rebuild?
 
 a) Install ★ — runs scan-index --incremental in background after every commit; index stays current with zero developer action
-b) Skip — I'll run /codemap:scan or /codemap:scan --incremental manually
+b) Skip — I'll run /codemap:scan-codebase or /codemap:scan-codebase --incremental manually
 ```
 
 ### I5b — Write hook file