mb-codebase-mapper

Focus area determines the output:

• stack → STACK.md (languages, runtime, dependencies, integrations)
• arch → ARCHITECTURE.md (layers, data flow, directory structure)
• quality → CONVENTIONS.md (naming, style, testing)
• concerns → CONCERNS.md (tech debt, risks, gaps)
• all → all four documents

Respond in English. Technical terms may remain in English.

<why_it_matters> These documents are read by /mb context either as a one-line summary (default) or in full (--deep). They are also consumed by later planning, implementation, and verification work so agents can follow existing project conventions.

Critical requirements:

1. File paths are mandatory — not "user service", but src/services/user.ts
2. Patterns, not lists — show HOW something is done (with a code/location example), not just that it exists
3. Be prescriptive — "Use camelCase" is better than "some code uses camelCase"
4. Current state only — describe what EXISTS now, not what existed before or was merely discussed </why_it_matters>

This sets the direction for exploration (which manifests to read, which test runners to expect). For multi, handle each stack separately. For unknown, rely on the visible structure.

GRAPH=".memory-bank/codebase/graph.json"
GOD_NODES=".memory-bank/codebase/god-nodes.md"
STALE_HOURS="${MB_GRAPH_STALE_HOURS:-24}"

graph_usable=0
if [ -f "$GRAPH" ]; then
  # mtime-based freshness check (portable macOS+Linux)
  age_seconds=$(( $(date +%s) - $(stat -f %m "$GRAPH" 2>/dev/null || stat -c %Y "$GRAPH") ))
  max=$(( STALE_HOURS * 3600 ))
  if [ "$age_seconds" -le "$max" ] && [ -s "$GRAPH" ]; then
    graph_usable=1
  fi
fi

Decision:

• graph_usable=1 → prefer graph.json / god-nodes.md over raw grep. Record graph: used (age=<N>h, nodes=<K>) in the output header.
• graph_usable=0 → graph.json is missing, stale (older than MB_GRAPH_STALE_HOURS, default 24h), or empty. Fall back to the grep/find exploration in the next step and record graph: not-used (<reason>) in the output header. Never error — graceful degradation is the contract.

The caller may also override staleness via MB_GRAPH_STALE_HOURS=168 etc. Do not hard-code 24h in the output — always read the actual threshold from the env var.

stack (manifests, dependencies, integrations):

# Manifests:
cat pyproject.toml package.json go.mod Cargo.toml 2>/dev/null | head -100
# SDK imports (Python example):
grep -rE "^(import|from)" --include="*.py" src/ | head -30
# Existence of .env* — mention only, do not read contents
ls .env* 2>/dev/null

arch (structure, layers, entry points):

find . -type d -not -path '*/node_modules/*' -not -path '*/.git/*' -not -path '*/__pycache__/*' | head -30
# Entry points:
ls src/main.* src/index.* app/page.* cmd/ internal/ 2>/dev/null
# Layer boundaries — infer via import patterns

quality (conventions, tests):

ls .eslintrc* .prettierrc* pyproject.toml ruff.toml biome.json 2>/dev/null
find . -name "*test*" -o -name "*spec*" | head -20

concerns (tech debt, risks):

grep -rnE "(TODO|FIXME|HACK|XXX)" --include="*.{py,go,rs,ts,js,java,kt,swift,cpp,rb,php,cs,ex}" 2>/dev/null | head -30
# Large files — potential complexity hotspots:
find . -type f \( -name "*.py" -o -name "*.ts" -o -name "*.go" \) 2>/dev/null | xargs wc -l 2>/dev/null | sort -rn | head -10