Hotspot Report (which hand-authored files are too many people editing)

Developer infrastructure: the readout that finds the hand-authored files many agents edit at once — the design defect behind most sync conflicts. It ranks by distinct commits in a window, keeps generated files out of the ranking and lists them separately as rule-zero offenders, and names a one-line split proposal per hotspot. Read-only, always exits 0.

This is developer infrastructure, not an end-user feature. It is the readout that enforces the trunk-at-scale contract's rule hot-files-are-split.

What it is

At 20,000 commits a day, the thing that costs the most is a file many agents edit at once: every one of them conflicts, and every conflict costs a conversation. The fix is a design change — split the file so different features live in different files, and a shared list becomes one file per entry — but you cannot fix what you cannot see.

This is the seeing. It answers one question: which hand-authored files are shared by the most work this week?

Where to find it

Running it

npm run churn:rollup -- --split-report                 # default 7-day window
npm run churn:rollup -- --split-report --window-days=2

It is a mode on the existing churn:rollup script, not a new npm script — the brief that asked for it also asked for no package.json change.

How it behaves

Reading it

HAND-AUTHORED HOTSPOTS (15)
    42  scripts/worktree-ready.mjs
        -> split by feature — 42 commits this week and held in 4 sync conflicts
    39  src/main/services/cloud/box-provider.ts
        -> split by feature — 39 commits this week; consider one file per entry if it is a shared list

RULE-ZERO OFFENDERS — generated, never a hotspot (2804)
   166  .claude/memory/anchors.generated.json   [driver: anchor-index]
   102  scripts/registry/lib.mjs   [rule-zero path]
    80  master-test-floor/_floor.json   [rule-zero path]

Two things about that output are deliberate:

A generated file is never a hotspot. It has no design to fix, and ranking one would send someone to refactor a file no human wrote. They are listed separately, with the count, so the rule-zero problem stays visible rather than hidden.
Each offender names the mechanism that excluded it. driver: <name> means the merge-driver classifier caught it; rule-zero path means the contract's own path list did. The two are different facts and are never merged into one label.

Why it does not use the churn reader

The existing churn:rollup reads commits through readAuthoredCommits, which asks git for --numstat — that needs blob content. On a blob:none partial clone with lazy fetching off, git log --numstat dies with a promisor fetch error and the reader returns nothing, so an unreadable repo is indistinguishable from a quiet one.

Ranking needs only which files a commit touched, never line counts, so this reads with --name-only — no blob content required, and cheaper.

The window may be shortened, and it says so

On a partial clone a long window can be unreadable while a short one is fine — measured here, 7 days fails and 2 days succeeds, and it is a property of the window, not of any flag. When that happens the report halves the window until the read succeeds and states the reduction in its own first line:

NOTE: the 7-day window could not be read on this clone; reporting the
last 3 day(s) instead. A shorter honest window beats a longer fabricated one.

It never prints a shorter window as though it were the one you asked for.

What it is not

Not a governor. It always exits 0. It does not gate a merge, throttle a land, or fail a build.
Not the acceleration view. --hotspots on the same script is a different readout (RT-F022): it flags files accelerating above their own churn baseline. This one measures volume — which file the most work shares. A file edited steadily 55 times is invisible to the first and is the headline here.
Not a fix. It reports; a person decides what to split. Filing a refactor task per hotspot is a separate step.

Where the numbers come from

number	source
commits per file	`git log --min-parents=1 --max-parents=1 --name-only`, so parentless roots are not counted as authored work
held conflicts	the master sync's durable conflict records, counting only `kind: conflict` with `state: held` — a settled conflict is solved work and is not counted
generated	`isRegenerableGeneratedPath` with the path's real merge driver, plus the contract's rule-zero path list for what that classifier misses

master-sync.md — the sync whose held conflicts this report counts.
repo-foundations.md — the repo-health foundations this readout supports.

Last verified 2026-10-04