code-context-map

code-context-map

Act as a senior/staff engineer producing a durable, AI-readable structural map of a codebase.

Goal: Generate a ranked, token-budgeted, layered Markdown "code context map" of a target project (files, imports, signatures, invoke edges, and typed external boundary calls), write it to a gitignored folder inside that project, and regenerate it on invoke so an AI assistant reads the map first and knows precisely what to read, index, and test before changing code. A chain:<seed-file> scope additionally walks one file's import chain by direction with a hop cap, extracting with ripgrep by default and with a parser when one is already present (ADR-0057 D-2, D-5). The map ORIENTS; it is a seed for grep, not a replacement for reading the code. Follows templates/CODE_CONTEXT_MAP.template.md.

This command is opt-in, not part of default task init (use it for structural orientation, onboarding, or a stale map). The governing decision is docs/adr/0027-code-context-map-and-product-repo-artifacts.md.

Mandatory context bootstrap (before any output):

• Read these sections in WORKFLOW_OPERATING_SYSTEM.md first:
  • ## LLM execution contract
  • ## Editor mode policy (mode definitions only; the tool mapping table is lazy-loaded in wos/editor-mode-mappings.md and needed only for non-Claude-Code tools)
  • ## Global output contract (including Adaptive handoff and Mode selection rule)
  • ## Cross-cutting workflow guardrails
• Bootstrap tiers: the light-weight commands (branch-commit, what-next, where-we-at, slice-closure, compact-task-memory) plus the high-frequency implement-approved-slice and sync-task-state (v3 wave1 item D) read the four sections above with two subsections of ## Cross-cutting workflow guardrails skipped: ### External web access (centralized) and ### Sequencing heuristics (by phase). Everything else is read at every tier, including ### Proposal vs approved persistence and ### Substrate peer ownership (per ADR-0034), since all seven write substrate sections and reason about PROPOSED (state-reconcile stays on the full tier for cross-artifact judgment). The full tier is measured at 12109 tokens, the four always-read sections combined; the two skipped subsections are 1,034 of those (measured 2026-09-28), so the reduced tier is about 11,074. The leaf-reviewer tier (verify-against-rubric, ADR-0226) reads only ## Global output contract, measured at 5215 tokens, plus its rubric.
• Session bootstrap reuse (skip-if-unchanged; v3 wave1 item D): WHEN this conversation already read the bootstrap sections in an earlier turn still VISIBLE in the context window AND WORKFLOW_OPERATING_SYSTEM.md has not changed since, the command MAY skip the re-read and cite the earlier one, emitting one Command transcript line: Bootstrap: reusing turn <N> read, WOS unchanged. Scoped exception to the context-budget re-fetch rule (wos/context-budget.md, "The re-fetch rule"), because these sections are one large, static, byte-identical read repeated every turn; every other tool result still re-fetches. VISIBLE means the section text itself is still present and quotable now, not merely that a record of the earlier read exists: a harness that clears a tool result while the record survives (ADR-0114) has not satisfied VISIBLE, and self-declared memory after a compaction never qualifies. A stateless-per-turn harness is excluded. The transcript line is mandatory; a silent skip is invalid output.
• Resolving the spec and wos/<topic>.md: canonical repository FIRST. Otherwise use active-adapter docs: ~/.claude/workflow-docs (CLAUDE_WORKFLOW_DOCS_DIR), ~/.cursor/workflow-docs (WORKFLOW_DOCS_DIR; project .cursor/workflow-docs on project installs), ~/.codex/workflow-docs (CODEX_WORKFLOW_DOCS_DIR), or <kimi-home>/workflow-docs (KIMI_WORKFLOW_DOCS_DIR). Nonempty overrides win. Kimi home: KIMI_CODE_HOME, else existing ~/.kimi-code, else existing ~/.kimi, default ~/.kimi-code. Use one root for both paths; try other adapters if absent or unknown. Report resolved root, fallback to other adapters, or missing mandatory context in ### Command transcript. Installed snapshots refresh and prune retired topics only on sync.
• Read additional sections only when relevant to this command's role.
• Align all routing recommendations and next-command suggestions with the current command set.
• Official next-command names only: recommendations, including Run now, use registered names from commands/<name>.md or commands/<name>/SKILL.md; installed mode uses the available Fhorja command or skill inventory. No invented aliases. Run now: none with Mode: N/A ends only if no honest next step exists, defined under ### Official command names (routing integrity) (ADR-0126). Required inputs:
• target codebase path (the project to map; the map is written inside this path). When a task is active and SOURCE_OF_TRUTH.md names the workspace, default to that.
• scope, one of:
  • digest (default): Layer 1 only (repo digest + module-to-file import adjacency + boundary summary). Cheapest; always safe for a whole repo.
  • module:<path/glob>: Layer 1 plus Layer 2 detail (ranked signatures, invoke edges, typed boundary edges) for the named module(s). Use for the area the current task touches.
  • chain:<seed-file>: Layer 1 plus a seed-anchored import-chain walk from <seed-file> (ADR-0057 D-5). Answers "what does this file pull in, and in what order does the wiring run". Walks by direction with a hop cap and a cycle guard.
• optional (chain scope only): direction one of imports (default), dependents, or both; max-hops (default 4, or all for an unbounded walk until no new files are reached) caps the radius; cycle edges are recorded once and not re-walked. For a whole-repo view prefer the digest or module: scopes; a chain: with max-hops:all on a large repo trips the consent-gated fleet (D-4) by design.
• optional: token budget for Layer 2 (default 1200 tokens per module; raise only when justified). Layer 1 is always generated regardless of budget.
• optional: keywords:<comma-separated-terms> (task-scoped) to rerank Layer 2 symbols toward the current task. WHEN set, Layer 2 symbols are reranked by ripgrep term-frequency of these terms blended with the existing import fan-in via reciprocal rank fusion (RRF), and that Layer 2's ranking source is labeled structural + keyword. WHEN unset, ranking is import fan-in only, the source is labeled structural, and the output is byte-identical to prior behavior. Ripgrep-only: no embeddings and no vector index (ADR-0072, activating the optional rerank ADR-0027 D-8 deferred).
• optional: --explain-ranking flag to show, per Layer 2 symbol, its fan-in rank, its keyword-frequency rank, and the fused RRF score, so a reranked order is auditable. Off by default; WHEN off, the symbol-line format is unchanged, and WHEN keywords: is absent the flag adds nothing beyond the fan-in rank.
• optional: language hint (defaults to auto-detect by file extension; v1 ships pattern sets for TS/JS first and degrades gracefully elsewhere).
• optional: refresh flag (refresh to regenerate an existing map; default behavior is regenerate-on-invoke, so a non-stale identical map yields NO_OP rather than a rewrite).
• optional: --skip-secret-scan to bypass the pre-emit secret gate (ADR-0060); the command never auto-skips, so this is the explicit human override after a confirmed false positive.
• optional flags, host-rendered with no new dependency (full behavior in Operating rules below): diagram (append a Mermaid import-adjacency and invoke flowchart, node-capped, ADR-0047); sequence:<flow> (append a Mermaid sequenceDiagram for one named runtime flow); exemplars (1 to 3 blessed in-repo reference snippets a greenfield slice should mirror, ranked by fan-in); html (also emit a self-contained interactive MAP.html in the same gitignored folder, ADR-0057 D-3).