Home / Projects / Orchestrata Ultimate / Decisions / ADR index / ADR-0128

ADR-0128: The tracked codebase maps are regenerated at commit, by per-file delta, through the codetools ast map verb

field	value
Status	Accepted — Accepted (Mohamed, 2026-10-22: ruling "A", "maps should use delta", "do item 3 in orchestrata")
Date	2026-10-23
Register	factory (`docs/adr`, 4-digit ids)
Source	`docs/adr/0128-the-tracked-codebase-maps-are-regenerated-at-commit-by-per-file-delta-through-the-codetools-ast-map-verb.md` — recorded on branch `fix/ship-sanctioned-gate-pytest` at `8c7031c9a`, not yet on master
Wiki register entry	ADR-0128 (wiki status: Accepted)

← ADR-0127 · ADR-0129 →

The record

Status: Accepted (Mohamed, 2026-10-22: ruling "A", "maps should use delta", "do item 3 in orchestrata") · Date: 2026-10-23

Context

RUL-030 (Mohamed, 2026-08-13) keeps docs/CODEBASE_MAP.md and docs/CODEBASE_MAP_FULL.md tracked. Before this ADR, only the SessionStart hook inject-codebase-map.sh refreshed them, from scripts/gen_codebase_map.py. scripts/worktrees.py copied the primary checkout's map into new worktrees. So commits carried maps that described some other tree's state.

Measured on 2026-10-22:

Step	Wall time	Commit
Full regeneration (deterministic)	13.5 s	—
Ten separate `symbols` CLI calls, each unpickling the 200 MB warm cache	128 s	—
One process	about 15 s	e1f3a5047
Per-file delta cache, no-change run	1.0 s	c995f5b88
`codetools ast map` verb, warm	0.495 s	d4ae44819
`codetools ast map` verb, cold	10.9 s	d4ae44819

Equivalence: the codetools output differs from the script's only in the header and footer blockquotes, with no data line different.
Regression: a tree without docs/ got no maps on the codetools path, because the hook moved the files into a missing directory. It was caught by test_hook_regenerates_and_stages_both_maps_when_python_is_staged and fixed in a4cbc2bdf.

Decision (Mohamed, verbatim per rule)

"A" (item 2, 2026-10-22). The pre-commit hook regenerates both maps when a .py file is staged, and stages them. worktrees.py stops copying the primary's map. RUL-030 tracking stays.
"maps should use delta". Map regeneration, at pre-commit and at SessionStart, re-parses and re-renders only the changed modules. The output must be byte-identical to a full regeneration, and a test asserts delta == full.
"do item 3 in orchestrata". Regeneration goes through codetools ast map <tree> --with-full, configured by [tool.codetools.map] in pyproject.toml. scripts/gen_codebase_map.py stays as the fallback when codetools is not installed. A run with fewer than 1,000 signatures keeps the existing full map, the rule from the 2026-08-08 incident.

Alternatives rejected

Stop tracking the maps. My proposal; it conflicts with RUL-030.
Refresh at SessionStart only. Maps in commits stay stale.
Full regeneration on every commit. It costs 13.5 s per commit.

Consequences

Every commit that stages Python carries maps that match its tree. The pre-commit map step costs about 0.5 s warm.
The commit hook depends on the deployed codetools when it is present, with the script as fallback.
The hook must create docs/ itself (a4cbc2bdf).
Hooks run uv run --no-sync so they never flip the venv to an editable install (8a2cb42ad).

Provenance

Rulings: Mohamed, 2026-10-22: "yes start with 1 and 2" with item 2 ruled "A"; "maps should use delta"; "do item 3 in orchestrata and the still open tasks now".
Commits:
- 7fa34f61d (brief)
- b5468cb1c (pre-commit regenerates)
- e1f3a5047 (one process)
- c995f5b88 (delta cache)
- d4ae44819 (codetools verb)
- a4cbc2bdf (docs/ fix)
All are on GitLab master since 2026-10-22, when the push gate passed 134 tests.
codetools: b518f88a, the ast map fast path, 7.1 s down to 0.41 s warm.

No other ADR is named in this record.

Rulings cited

RUL-030: RUL-030 — Generated artifacts belong in git

Specs cited

None (or no spec page exists for the ones named).