Orchestrata Ultimate › Plans › briefs › 2026-10-22-precommit-regenerates-maps-builder

Brief — every commit carries a fresh codebase map, so new worktrees start clean (Sonnet builder)

Source: plans/briefs/2026-10-22-precommit-regenerates-maps-builder.md at 8a2cb42ad · last changed 2026-10-22 · first committed 2026-10-22 · 83 lines.

Prose pending.

Plan text

Brief — every commit carries a fresh codebase map, so new worktrees start clean (Sonnet builder)

Executor: Sonnet builder (Claude Code builder agent). Worktree (cwd): /home/mohamed/workspace/wt-MAP-PRECOMMIT, branch fix/precommit-regenerates-maps, off origin/master 4ac0db570. The venv is provisioned (uv sync --dev with env/toolchain.env sourced). The tree is clean.

DESIGN_WAIVER: RUL-030

Ruling (Mohamed 2026-10-22, option "A"): keep the maps tracked, as RUL-030 requires, and have the pre-commit hook regenerate them whenever a commit stages Python. Then a checkout of any commit matches its maps.

GOAL: a new worktree and a new session leave git status clean.

Measured (orchestrator, 2026-10-22):

docs/CODEBASE_MAP.md and docs/CODEBASE_MAP_FULL.md are tracked artifacts in the RUL-030 registry (scripts/check_generated_artifacts.py, GENERATED_ARTIFACTS); their generator is .claude/hooks/inject-codebase-map.sh.
The committed copies were last regenerated in 191765874 (2026-10-18), but master is at 2026-10-22. So the SessionStart hook rewrites them in every new checkout: +760/−975 lines in wt-INT-LAND.
The hook is deterministic: two runs in wt-INT-LAND gave byte-identical output, about 13.5 s each.
scripts/worktrees.py _copy_untracked_config also copies the primary checkout's docs/CODEBASE_MAP_FULL.md into every new worktree. Its docstring still calls the file gitignored, which stopped being true with RUL-030. This worktree showed M docs/CODEBASE_MAP_FULL.md straight after worktrees.py create; the orchestrator restored it.

Design (decided):

scripts/hooks/pre-commit: after the ruff stage has re-staged files, check git diff --cached --name-only --diff-filter=ACMRD. If it lists any *.py:
- run HOOK_REPO_ROOT="$PROJECT_ROOT" bash "$PROJECT_ROOT/.claude/hooks/inject-codebase-map.sh";
- then git add docs/CODEBASE_MAP.md docs/CODEBASE_MAP_FULL.md. If regeneration fails, the commit still goes through: print one WARN: line naming the failure, and never block. Do not change the ADR-0101 walls ledger fields.
scripts/worktrees.py _copy_untracked_config: stop copying docs/CODEBASE_MAP_FULL.md, and remove that bullet from the docstring. The file is tracked, so every checkout already has it.
Nothing else changes: not the map generator, not the session hook, not the RUL-030 registry.

This commit stages scripts/worktrees.py, so the new pre-commit regenerates the maps in this same commit. That is the one-time catch-up; do not regenerate or stage the maps by hand.

Read Python with the AST toolkit (scripts/serialize_codebase_ast.py symbols|source|refs --no-daemon), never by hand. Shell and markdown can be read directly.

CONSTRAINTS:

RUL-037: write Python only with the file tools (Write/Edit). No python -c, no heredoc into an interpreter, no shell writes to files.
No mocks, no monkeypatch, no skips, no xdist. Function-scope fixtures only. Run tests only through scripts/run_tests.py.
One commit on the branch, author Mohamed, with no AI attribution of any kind. Never --no-verify, never push.
If a test needs the real map generator in a scratch repository and that cannot work within the existing harness of tests/scripts/test_hooks_pre_commit.py, STOP and report. Do not fake the generator.

FILES:

scripts/hooks/pre-commit
scripts/worktrees.py
tests/scripts/test_hooks_pre_commit.py
tests/scripts/test_worktrees.py
tests/scripts/test_worktrees_provision.py
docs/CODEBASE_MAP.md
docs/CODEBASE_MAP_FULL.md
reports/precommit-walls.ndjson
plans/briefs/2026-10-22-precommit-regenerates-maps-builder.md

The two maps and the ledger are written only by the hooks, never by hand.

DONE WHEN:

Tests prove two things in tests/scripts/test_hooks_pre_commit.py, following its existing harness:
- a commit that stages a .py stages both maps;
- a commit that stages only non-Python files does not run the map step.
A worktrees test proves create no longer copies the map (change whichever of the two worktrees test files covers _copy_untracked_config).
The VERIFY run is green.
After the commit, both of these leave git status --porcelain empty in this worktree:
- HOOK_REPO_ROOT=$PWD bash .claude/hooks/inject-codebase-map.sh;
- .venv/bin/python scripts/check_generated_artifacts.py.
REPORT (below) records:
- the commit sha;
- the pytest summary line;
- the extra wall time the map step adds to your own commit;
- the git status output from the check above.

VERIFY (time budget agreed with Mohamed before dispatch; cap every run with timeout 300):

timeout 300 .venv/bin/python scripts/run_tests.py tests/scripts/test_hooks_pre_commit.py tests/scripts/test_precommit_walls_ledger.py tests/scripts/test_check_generated_artifacts.py tests/scripts/test_gen_codebase_map.py tests/scripts/test_session_start_hooks.py tests/scripts/test_worktrees.py tests/scripts/test_worktrees_provision.py --skip-gates

Brief — every commit carries a fresh codebase map, so new worktrees start clean (Sonnet builder)

Plan text

Brief — every commit carries a fresh codebase map, so new worktrees start clean (Sonnet builder)

REPORT

Related