doc-architecture-module-map

Packet · {{ repo }} · architecture/module-map.md

1. Objective

Produce {{ docs_root }}/architecture/module-map.md: one H2 per top module, each with a one-paragraph description and a bullet list of the module's top 8 files cited as `path:LOC` with (N LOC) suffix.

2. Scope

• Create: {{ docs_root }}/architecture/module-map.md
• Do not touch: any other file under {{ docs_root }}/, any source file in the repo, .context.md, .prefetch.md, or any .packets/*.md other than this one.

3. Input specification

Source	Read how	Cache state
Shared context	Read {{ context_path }}	always first
Prefetch ledger	Read {{ prefetch_path }}	always first
Top communities	{{ context_path }} § Top communities	cached
Community member files	{{ prefetch_path }} § community members or mcp__codehub__sql({query: "SELECT name, file_path, start_line FROM nodes WHERE kind='File' AND community_id = <id> ORDER BY file_path"})	cached if digest present
Community relations	mcp__codehub__context({symbol: <community-name>}) per module	mid-run (only if cache miss)
File LOC	Read <file> then count lines	mid-run

4. Process

1. Read {{ context_path }} and Read {{ prefetch_path }}. Confirm {{ repo }} profile and the ordered list of top communities.
2. For each of the top 8 communities, pull the member file list from .prefetch.md § community members. If absent, call sql({query: "SELECT name, file_path, start_line FROM nodes WHERE kind='File' AND community_id = <id> ORDER BY file_path LIMIT 50"}) and cache the digest in this packet's Work log.
3. For each module, rank files by semantic weight (inbound relation count from cached context digest if present, else alphabetical fallback). Keep the top 8.
4. For every file in the shortlist, Read it to compute LOC. Record path:LOC + total line count per file in the packet Work log.
5. Draft the one-paragraph description per module. Anchor the paragraph on the module's inferred_label and its highest-weight file, each cited `path:LOC`.
6. Collapse any module with fewer than 3 files into a trailing ## Supporting code H2 that lists those files as flat bullets.
7. Write {{ docs_root }}/architecture/module-map.md with H1 = {{ repo }} · Module map and one H2 per module in top-community order.