Code Module Summaries

Overview

Build and maintain evidence-backed Markdown summaries for an arbitrary Git repository. Treat each module's last successful commit SHA as its incremental checkpoint. Timestamps and Markdown mtimes are display metadata only.

The tracked control directory is the source of truth:

• registry.json: stable module boundaries, layout, and summary paths.
• state/<module-id>.json: one independent checkpoint per module.
• modules/*.md: summaries when using the centralized layout.
• INDEX.md: links and module ownership; update only when mappings change.

Invocation

Interpret user arguments with this contract:

/code-module-summaries [repo]
  [--output <control-dir>]
  [--layout centralized|colocated|custom]
  [--update]
  [--module <id-or-exact-name>]...
  [--target <git-ref>]
  [--refresh-modules]
  [--summary-name <filename.md>]
  [--head-only]
  [--accept-summary-drift]
  [--adopt-existing-summary]
  [--rebaseline --reason <text>]

Defaults:

• repo: current Git root.
• --output: code-summaries/.
• --layout: centralized.
• --target: the registry's tracked_ref, normally HEAD.
• --summary-name: MODULE_SUMMARY.md for colocated summaries.

--layout custom places each module's Markdown at an arbitrary in-repository .md path declared per module in registry.json (summary_path), with no fixed directory shape. This is the layout for a shared conclusions/-style tree, for example enterprise/conclusions/apps/gateway_conclusion.md. A custom registry may also declare a top-level index_path (e.g. enterprise/conclusions/README.md): a managed overview file the agent maintains, excluded from module source diffs and unassigned-path checks. See REFERENCE.md §9 for exact rules. centralized and colocated are unchanged.

--module is repeatable and case-sensitive. It selects exact IDs first, then an exact unique name. Never use fuzzy matching for a write operation.