Add report-only module-shape measures: placement legibility (Jev) and change-coupling modularity

[thymikee]

Purpose

Add two report-only measures of module shape to the repository tooling, so "name modules for the domain question they answer" (AGENTS.md) becomes a number we can watch instead of a taste judgement:

1. Placement legibility — can an outside reader file a module into its owning family from its imports, its test path, and its first-touch commit subject alone? Measured by asking the typesafe-ai/jev evaluation model through AI Gateway, one choice question per file, scored against where the file actually landed.
2. Change coupling — do the physical families match how the repo actually changes? Measured from git history alone (logical coupling / co-change), with per-family modularity.

Both were prototyped outside the repo and produced the findings in Evidence below. This issue is to rebuild that prototype as first-class repo tooling with the guards the prototype had to discover by hand.

Neither measure gates anything. They are advisory reports, like pnpm depgraph, and they must not fail CI.

Evidence (measured, current tree)

Corpus: 1,726 production files, 39 families (23 packages/* + 16 src/ zones including (root), vendor, platform-runtime).

Baselines and the model, same 1,726 files, 39-way choice (random = 2.6%):

	accuracy
majority family	18.1%
neighbour-vote over import paths	28.3%
k-NN over import-path sets	42.8%
Jev, reader-view	49.7% (1,357,479 tok, $0.057, 47s, 44 batches of 40)

Test–retest agreement across two independent calls: 96.4% over 302 files (accuracy 53.6% vs 53.0%).

Ablations, 302-file sample — these are why leakage control is the hard part of this issue:

evidence condition	accuracy
bare file names, no directory names anywhere	37.4%
family-relative paths, family ids withheld	36.1%
real import paths, test basename, redacted subject (scored condition)	53.6%
+ full test path (mirror leak)	67.5%
+ verbatim commit subject (naming leak)	71.2%

The prototype's "scored condition" row above is what this issue now calls the reader condition, and its two ablation rows are the name-withheld condition; the naming is fixed in Required behaviour so a rebuild cannot score the wrong one.

Own-family leakage before redaction: commit subject 51.7% (893/1726), import evidence 21.8%, local test path 7.7%. One redaction pass scrubbed 1,684 field-level hits.

Per-family spread under the scored condition, best → worst: selectors 96.8, managed-allocation 96.6, session-journal 100 (n=7), host-kit 84.1, platform-android 78.1, provider-webdriver 76.7, platform-apple 74.3, capture-kit 63.0, commands 57.6, maestro 57.1, daemon-server 40.7, cli-schema 37.5, mcp 33.3, screenshot-diff 28.6, kernel 27.3, core 14.3, cli 13.8, contracts 12.1, (root) 1.3, sdk 0.

Coupling, from 1,044 usable commits of 1,979 (34 mass-migration commits excluded): 6,337 edges at support ≥ 3, of which 4,084 (64.4%) cross families. Coupling kept inside its own family: 36.4% observed vs 11.4% expected for that size distribution → modularity 0.250; last 120 days 39.3% / 0.278. Of commits spanning ≥ 2 families the median spans 4, and 40% span ≥ 5 (42% over the last 120 days).

The two axes are independent, which is the point: host-kit is legible (84.1%) with in-family coupling weight 0.2 and out/in ratio 177 — a toolbox, not a module — while cli has modularity 0.0126 (third strongest community) and legibility 13.8%, and maestro is the only family whose coupling is mostly internal (out/in 0.6) at legibility 57.1%.

Required behaviour

Layer A — deterministic history model and coupling (no network, no new dependency)

Create three module groups:

• scripts/repo-history/ — the single rename-resolved history model both reports consume.
  • renames.ts: build an oldPath → newPath map from every R record in git log -M --name-status, and a resolve(path) that applies it transitively (cycle-guarded, memoised) so a historical path reaches today's path.
  • records.ts: per current production file, the first commit whose rename-resolved record adds or renames it: { id, sha, date, subject, status: 'A' | 'R' }.
  • commits.ts: per commit, the set of rename-resolved current production file ids, plus its date and subject.
• scripts/coupling/ — logical coupling from that model.
• scripts/legibility/ — corpus, redaction, baselines, evaluation client, scoring.

Formulas, exactly:

• Affinity. For a commit touching k ≥ 2 production files, add 1 / (k − 1) to each unordered pair; support = number of commits containing the pair. Skip commits with k > 60 and report how many were skipped and which. Keep edges with support >= 3.
• Family modularity. Let W = total kept edge weight, in_f = weight of edges with both ends in family f, out_f = weight of edges with exactly one end in f, s_f = 2·in_f + out_f. Then intraShare = Σ_f in_f / W, expected = Σ_f (s_f / (2W))², and per family Q_f = in_f / W − (s_f / (2W))². Σ_f Q_f must equal intraShare − expected; assert that identity in a test.
• Family span histogram. Per commit, the count of distinct families touched; report the histogram, the median over commits spanning ≥ 2 families, and the share of those commits spanning ≥ 5.
• Compute everything twice: over all history and over the trailing window (--since-days, default 120), so drift is visible.

Layer B — legibility oracle (network, opt-in)

• Families and ground truth come from the gate's own model. Import listSourceFiles from scripts/layering/check.ts and derive the zone partition through scripts/layering/model.ts (see scripts/depgraph/load.ts for the reuse pattern). Do not re-derive zones, file sets, or package prefixes anywhere else.
• Evidence per file, in this order: value-imports resolved to real repo paths (the file's own path never shown), external package specifiers verbatim, the mirrored test file's basename, and the first-touch commit subject with the conventional-commit type(scope): prefix and trailing (#NNNN) stripped.
  • Value imports only: static import/export … from with at least one non-type binding. Exclude import type, type-only specifiers, and dynamic import().
  • Test mirror resolution, in priority order: same directory, sibling __tests__/, then <family root>/{test,__tests__}/ by shortest path; if the match lives in another family, mark it foreign and do not show that family's id.
• Two conditions; only one is the score. The reader condition shows resolved import paths, the mirrored test's basename, and the subject with the type(scope): prefix and (#NNNN) stripped, hiding only the file's own path; family ids stay scrubbed out of the subject in both conditions, since a subject narrates a change rather than a layout. That is what someone opening the tree sees, and it is the only condition the three baselines — which read the physical layout of every other file — are comparable to. A name-withheld condition additionally replaces every family id in the answer space with a fixed «x» placeholder in the paths, subject, and test path, matched as a word sequence so hostKit, host/kit, and Host Kit go with host-kit. It runs behind --ablation, costs a second full pass, and is reported as the gap to the reader number: that gap is what names carry. It is never a score and never sits next to the baselines. Redaction stays mandatory where it applies: the withheld pass reports its own scrubber defect rate and the run refuses to continue above 1% of files. The reader condition prints the same audit as a name echo rate — files whose evidence already names their own family — which is a property of a legible tree, so it is reported and not capped.
• Baselines are required output. Majority, neighbour-vote (modal family among import targets), and k-NN (Jaccard over import-path sets, self excluded) must be computed and printed next to the model result. A legibility number published without the k-NN column is not usable.
• Score output: overall accuracy vs all three baselines; a per-family row with files, sampled n, model accuracy, k-NN accuracy, delta, median provider confidence, Q_f, and out/in flow; and a divergence list of files where the model and k-NN independently agree on a different family, annotated with whether the file arrived there via a rename.
• Two named upper-bound conditions may be kept behind flags (--with-test-dir, --raw-subject) and must always be printed as leak references, never as the score.

CLI and output shape

Mirror the depgraph conventions exactly:

pnpm coupling                        # -> .tmp/coupling/report.json + text summary
pnpm coupling --since-days 30 --out /tmp/coupling.json
pnpm legibility                      # sample run, 300 files, seeded
pnpm legibility --all --out .tmp/legibility/report.json
pnpm legibility affected packages/capture-kit/src   # future query; do not build now

Report JSON: { generated: { commit, date, files, families }, baselines, perFamily: [{ family, files, n, accuracy, knn, delta, medianConfidence, modularity, outInFlow }], divergences: [{ id, family, predicted, p, viaRename, subject }] }. Coupling JSON: { generated, window: { since, allTime }, assortativity, perFamily: [{ family, files, inWeight, outWeight, outInFlow, partners, Q }], hubs, familyPairs, edges }.

Add pnpm legibility, pnpm legibility:test, pnpm coupling, pnpm coupling:test, pnpm repo-history:test as node --experimental-strip-types entries. Wire the three *:test scripts as model gates following the depgraph precedent: ids in the CheckId union and the ordered list in scripts/check-affected/model.ts, gate(...) entries in scripts/check-affected/checks.ts, run-gate steps in .github/workflows/ci.yml next to the existing gate: depgraph step, and the test scripts in check:tooling. The report commands themselves stay ungated.

Guards

1. Never leak the answer into the evidence. The file's own path is never shown and family ids stay scrubbed out of the subject under both conditions — a subject narrates a change, not a layout. Under the name-withheld condition every family id in the answer space is scrubbed out of the paths, subject, and test path, and that defect rate is capped at 1%; under the reader condition the same audit is the name echo, printed and not capped. The conditions that reintroduce the mirror-test path or the raw subject stack on the reader line and are labelled leak references at the point of output. Regression-proof this: plant a file whose subject contains its own family id and show the audit names it under both readings.
2. No second source of truth for zones, file sets, or edges. Everything physical comes from scripts/layering/. A locally reimplemented zone map or import resolver is a rejection, per the AGENTS.md rule about not reconstructing another source of truth.
3. Report-only. No threshold fails the build; no ratchet; no allowlist. These numbers move with history. Nothing here is added to check:layering, check:fallow, or any check:* gate beyond the model tests.
4. No network in unit tests. The evaluation call sits behind one injected seam; unit tests use a fake that returns canned answers. pnpm legibility:test, coupling:test, and repo-history:test must pass offline, in CI, with no key.
5. Model-call quirks are handled at the client, not papered over. With 39 options and provider rounding to two decimals, a tie at the top fails whole-call validation (did not select a highest-probability option) and would discard every answer in that batch — observed 4 times in a 44-batch full pass. Required behaviour: split the batch in half and retry, recursively; a file that still cannot be answered is recorded as unanswered with a typed reason, never silently dropped, and the run prints the split count and unanswered count.
6. Secrets and spend. Read the key from the environment only; never log or echo it. Fail with an actionable typed message when it is missing. Print token and cost totals. Default to a seeded 300-file sample; a full-tree pass requires an explicit --all. Cap requests per run and stop with a message at the cap.
7. Deterministic sampling. Seeded, stratified by family, at least one file per family, same seed ⇒ same file set, recorded in the report.
8. Never commit stamped output. Reports go to .tmp/; docs/agents/testing.md forbids run-stamped output under scripts/. Committed fixtures for tests are fine.
9. Nothing under src/, packages/, apple/, or android/ changes. This issue is tooling only. The refactors in Out of scope are not licence to touch production code.
10. Repository mechanics. pnpm only, never npm install artifacts; pnpm format repository-wide; OXC lint clean; keep every new file well under 1,000 lines; tests mirror source one-to-one (a module and its test are created together, no additions to an aggregate test file); no new barrels. Stage a new module before trusting a layering-scan result, since it reads tracked files only.
11. ai dependency. The pinned ai@7.0.68 predates experimental_evaluate; the declared range ^7.0.68 already admits a version that has it, so update the lockfile resolution only — do not widen the range, do not add a new dependency, and do not move ai out of devDependencies.

Data shape for the evaluation call

experimental_evaluate from ai, not a chat-completions endpoint — typesafe-ai/jev is an evaluation model and chat completions rejects it with ModelTypeMismatchError.

experimental_evaluate({
  model: 'typesafe-ai/jev',
  state: { task, families, evidenceLegend },   // shared framing, sent once per call
  questions: { f0: { type: 'choice', instructions: `<fixed task text>\nEvidence: ${line}`, criteria } },
});

• criteria maps all 39 family ids to null. Family descriptions must not be supplied: the metric is whether the name carries the question, so a gloss would measure the gloss instead.
• One call carries ~40 questions. Measured: ~31K tokens per 40 files, ~1s per batch, 1.36M tokens and $0.057 for the full tree. Output tokens are priced at zero; input is $0.042/M.
• Auth: AI_GATEWAY_API_KEY. Provider confidence, when present, is at providerMetadata.typesafe.confidence[questionId] — it is a separate statistic from the selected option's probability and must be reported as such.
• Answers are rounded to two decimals; keep the raw choice, the selected probability, and the top-3 distribution.

Acceptance criteria

Layer A:

• pnpm coupling writes .tmp/coupling/report.json and prints: commits used/skipped with the skip threshold, edge count and cross-family share, intraShare vs expected and modularity for all-time and the trailing window, the per-family table, the top coupling hubs with their out-family count, the heaviest family pairs, and the family-span histogram including the ≥ 5 share.
• pnpm coupling:test and pnpm repo-history:test pass offline, and hard-assert on a committed synthetic fixture mini-repo (not on the live tree): affinity normalisation, support cut, the Σ Q_f = intraShare − expected identity, and transitive rename resolution across a two-hop rename.
• A rename applied twice in history resolves to the current path, and a historical path that no longer exists is dropped rather than counted.
• The mass-migration skip is proven: fabricate a commit touching more than 60 production files in the fixture and show it is excluded and counted.
• Live-tree values land in the ranges recorded in Evidence (modularity 0.20–0.35, ≥ 60% of kept edges crossing families, ≥ 25% of multi-family commits spanning ≥ 5). A miss is a printed drift warning naming the metric, not a failure.

Layer B:

• pnpm legibility --all reproduces, within ±3 points on the current tree, under the reader condition: majority ≈ 18%, neighbour-vote ≈ 28%, k-NN ≈ 43%, model ≥ 48%, and a per-family spread of at least 60 points between the best and worst family with n ≥ 20.
• pnpm legibility --all --ablation prints the name-withheld accuracy and its delta to the reader number, counts both passes in the token and cost totals, and never places the withheld number beside the baselines.
• The name-withheld scrubber defect rate is below 1% and is printed every run, next to the reader name-echo rate.
• A per-family row is emitted for every family with n ≥ 1, and the report never averages a family with n < 3 into any headline number.
• The split-and-retry path is exercised by a unit test with a fake that returns a tie-failing response, and the test proves: the batch halves, answers survive, and a permanently unanswerable file appears as unanswered with a typed reason.
• Missing AI_GATEWAY_API_KEY exits non-zero with a message naming the variable and the model id, and performs no requests.
• The three *:test scripts are registered as gates and owned by a workflow; pnpm check:gate-manifest, pnpm check:layering, pnpm lint, pnpm typecheck, pnpm format:check and pnpm check:tooling all pass.
• A README.md in each module group states which question the report answers, what the numbers do not mean, and the measured reference values — written in the scripts/depgraph/README.md register, including an explicit "this is not a removability or correctness claim" caveat.
• docs/agents/testing.md gains one pointer sentence for each report, next to the existing "Before editing a shared module" section. No other prose docs change.

Dependencies and sequencing

• Two PR-sized layers; Layer A first and independently useful. Layer A adds no dependency and needs no key. Layer B depends on scripts/repo-history/ from Layer A for first-touch subjects and rename status.
• AI_GATEWAY_API_KEY with access to typesafe-ai/jev is required only to run Layer B's report, never its tests.
• A fresh worktree needs pnpm install --frozen-lockfile && pnpm build before scripts/layering imports resolve to this checkout.
• pnpm legibility affected <path> is listed above as a future query only; do not build it here.

Out of scope (recorded findings for separate issues)

The prototype surfaced these. They are evidence, not work authorised by this issue:

• The command surface is one module split across five families. Coupling hubs: cli-schema/command-schema.ts (96.7 w, reaches 22 families), client/client-types.ts (89.4 w, 26 families; 297 lines, 18 exports, all types), cli-schema/cli-help.ts (85.8 w, 26 families; 1,255 lines), cli.ts (72.2 w), agent-device-client.ts (62.7 w), cli/parser/args.ts (46.9 w, 14 families), daemon/handlers/session.ts (46.9 w, 26 families), command-registry/registry.ts (42.4 w, 24 families; 1,997 lines). Driven by ordinary feature commits, and ≥ 5-family commit share is flat at 42% recently.
• cli-schema: 8 files, out/in flow 30, touches 29 of 39 families, Q ≈ 0, legibility 37.5% — the clearest wrongly-a-family candidate.
• src/daemon/replay/internal/session-replay-*.ts is the most common placement divergence (4 files, model and k-NN agreeing on ad-replay, which already exists) — an extraction left half-done. A reciprocal capture-kit/src/recording/output-path.ts ↔ host-kit/src/session-paths.ts swap sits next to it.
• Naming/routing payoffs where cohesion is real and legibility is not: cli (Q 0.0126 / 13.8%), maestro (Q 0.0121, out/in 0.6 / 57.1%), screenshot-diff (28.6%).
• contracts scores 12.1% legibility and this issue should not treat that as a defect: a vocabulary family's imports point outward at everything, so its legible surface is its entry names and its importers. Fixing the measure for rank-1 families needs in-edges as evidence; that is a follow-up, and any such change must keep the existing condition reproducible for comparison.

[thymikee]

Condition contract corrected, and the Layer B criterion now passes

The first rebuild of Layer B scored 37.5% against the model ≥ 48% criterion while reproducing every deterministic number. That was not a model shift: the issue asked for one evidence condition and named three ablations, and the rebuild scored the name-withheld ablation while printing baselines computed on unscrubbed physical paths. Information-asymmetric, so the model could not win it.

The contract in Required behaviour and Guards is now explicit and implemented:

• reader — real import paths, test basename, subject with type(scope): and (#NNNN) stripped, file's own path hidden, subject still name-scrubbed. This is the score, and the only condition the baselines are comparable to.
• name-withheld — the same evidence with every family id in the answer space replaced by «x». Behind --ablation, costs a second full pass, reported as the gap to reader and never beside the baselines.
• The own-family audit is now two readings of one function: a scrubber defect rate under withheld (capped at 1%, run refuses above it) and a name echo rate under reader (a property of a legible tree — printed, not capped).
• --with-test-dir and --raw-subject stack on the reader line and still print as leak references.

Measured on the full tree, commit a556e114cd, 1,726 files, 39 families, 0 unanswered:

condition	accuracy
majority	18.1%
neighbour-vote	30.1%
k-NN (k = 5)	43.6%
model, reader (the score)	52.3%
model, name-withheld ablation	38.1% (−14.2 vs reader)
leak reference: + test dir	67.0%
leak reference: + raw subject	64.0%

Name echo 702/1,726 (40.67%); scrubber defect 0/1,726. Spread with n ≥ 20: managed-allocation 100.0 → (root) 2.6, 97.4 points. Four passes cost 2,682,688 input / 2,354,385 output tokens, $0.1127. Seeded 300-file sample (seed 2677): reader 55.4%, ablation 40.2%, references 69.3% and 64.3%.

This closes the loop with the prototype rather than contradicting it: its 49.7% and this 52.3% are the same condition measured twice, and its 36–37% ablations are reproduced here as 38.1%. The −14.2 gap is the finding the issue was after — names carry 14 points of placement judgement on top of what neighbourhood alone gives k-NN.

Against the Layer B acceptance list: majority 18.1 vs ≈18, neighbour-vote 30.1 vs ≈28, k-NN 43.6 vs ≈43 (all inside ±3), model 52.3 ≥ 48, spread 97.4 ≥ 60.

Layer A is unchanged by this: modularity 0.250, 64.4% of kept edges crossing families, median family span 4, 40% of multi-family commits spanning ≥ 5.

Gates at this state: legibility:test 52 pass, coupling:test 20, repo-history:test 18, plus lint, typecheck, format:check, check:layering, check:gate-manifest.

[thymikee]

Collocation plan from the two measures

Which files to move, into which family, what each move is measured to change, and how to prove it before and after. Measured on main at 4c2ae0c with the Layer A formulas above (gate's own file set and zones, value imports only, 1,982 commits with renames resolved). The deterministic half reproduces this issue's numbers (Q 0.252 vs 0.250, 64.3% cross-family edges, same hub list), so the coupling deltas below are what pnpm coupling will print after each git mv. Jev deltas cannot be pre-computed; they are stated as expected direction with the mechanism.

Verdict: do two moves, bundle two small ones, refuse three.

Baseline

measure	value
production files / families	1,727 / 39
neighbour-vote / k-NN (k=5, ties expanded)	38.2% / 34.5%
Jev reader (from the comment above)	52.3%, name echo 40.7%
commits used / skipped (>60 files)	1,047 / 34
kept edges (support ≥ 3), cross-family	6,348 · 64.3%
intra / expected / Q	36.6 / 11.4 / 0.252
multi-family commits spanning ≥ 5	37.8%

Families the plan touches:

family	files	Jev	k-NN	Q	out/in
(root)	76	2.6%	7.9%	0.0000	31
cli-schema	8	37.5%	0%	0.0003	30
commands	132	57.6%	49.2%	0.0414	2.3
screenshot-diff	7	28.6%	14.3%	0.0021	1.3
capture-kit	162	63.0%	25.9%	0.0132	1.9
platform-runtime	1	n/a	0%	0.0000	∞
daemon-server	313	40.7%	86.9%	0.0765	1.6

Moves, ranked

Each what-if re-labels the files and recomputes the partition over the same commits.

#	move	files	Q	cross	≥5 share	verdict
1	cli-schema → commands/schema/	8	0.252 → 0.255	64.3 → 62.4	37.8 → 35.9	do
2	root platform-runtime-* → platform-runtime/	53	0.252 → 0.252	64.3 → 64.3	37.8 → 38.5	do
3	screenshot-diff → capture-kit	7	0.252 → 0.252	64.3 → 64.2	37.8 → 37.9	bundle
4	two single-file moves	2	0.252 → 0.253	64.3 → 64.1	37.8 → 37.6	bundle
5	replay helpers → ad-replay	7	0.252 → 0.250	64.3 → 64.7	37.8 → 37.9	refuse
all	1 + 2 + 3 + 4	70	0.252 → 0.260	64.3 → 63.5	37.8 → 38.5

Move 1 — fold src/cli-schema into src/commands/schema/.
Q ≈ 0, out/in 30, touches 29 of 39 families. command-overrides.ts is the clearest misplaced file in the tree: k-NN says commands at p = 1.00 and it co-changes with commands 6.6 vs cli-schema 3.5; cli-help.ts co-changes with daemon 21.5, commands 19.3, cli 6.5. Both zones are rank 3; consumers are cli (rank 6), mcp (rank 3, already imports commands in 16 files) and bin.ts. Moving to cli instead is a back-edge for mcp, so commands is the only legal target. This is the only move that reduces how many families an ordinary feature commit spans. Expect Jev: families 39 → 38, the 8 files join a 57.6% family; watch commands stay ≥ 55% at n+8.
Touch list: 8 production + 8 test files; 16 import sites in src/cli, src/mcp, src/bin.ts; literal path in src/cli/command-explain.ts:320; drop the rank entry in scripts/layering/model.ts and its test; 5 path-keyed entries in fallow-baselines/health.json; the AGENTS.md pointer line ("cross-surface schema composition in src/cli-schema"). Trap: cli-help.ts is 1,255 lines; a pure move carries it, do not split it in the same PR.

Move 2 — root src/platform-runtime-*.ts into src/platform-runtime/, prefix stripped.
(root) is 76 files at 2.6% legibility, 53 of them one flat family the model already names: UNRANKED_ZONES describes platform-runtime as "private implementation submodules of the canonical root composition", and the zone holds one file. No coupling change: in-weight 0.1 vs out-weight 26.8 (out/in 202), a toolbox by this issue's reading. The ≥5 share rises 0.7 because commits touching root and these files now count one more family; that is the honest cost. Expect Jev: root 76 → 24 (entrypoints and composition roots, matching docs/dependency-graph-findings.md §3). Strip the platform-runtime- prefix from file and test names so the gain is not a test-basename echo; compare the name-echo rate before and after and treat a rise as the move being cosmetic.
Touch list: 53 production + 32 test files; 23 root importers, 44 importers elsewhere (contracts 19, daemon 16, sdk 3, cli 2, core 1, platform-runtime 1, tests 2). Four layering policies pin the paths by literal: daemon-platform-runtime-inventory.ts (isRootPlatformRuntimeTarget regex plus edge targets), application-lifecycle-policy.ts, platform-composition-policy.ts (allowed composition specifiers), platform-package-policy.ts, plus their tests. Fallow baselines are path-keyed: move entries, never regenerate. Stage before running pnpm check:layering.

Move 3 — src/screenshot-diff into packages/capture-kit/src/screenshot-diff/.
Seven files whose only imports are @agent-device/capture-kit/png* and kernel; three importers (commands ×2, cli ×1). capture-kit Q 0.0132 → 0.0156, otherwise flat; too small for its own PR. Needs export entries in packages/capture-kit/package.json (R11 pins the exact list), a name that does not collide with ./screenshot-diff-pixels and snapshot/snapshot-diff.ts, and the rank entry dropped.

Move 4 — bundle into whichever PR touches the zone.

• src/metro/client-metro-companion.ts → src/client/: co-changes with client 2.6 vs metro 0.9, imports only the client tunnel contract, both rank 4.
• src/cli/batch-steps.ts → src/commands/batch/: k-NN commands p = 0.82, co-changes with commands 3.1 vs cli 1.0, only importer is src/cli.ts.

Move 5 — replay helpers into ad-replay: refuse.
The seven files under src/daemon/replay/internal/ with no daemon-relative import are the mechanical candidates (report-action, runtime-artifacts, suggestion-ranking, target-token, test-policy, trace, runtime-failure-response). Moving them lowers Q to 0.250 and raises cross-family edges to 64.7%: every one co-changes with the daemon (in-family weight 2.4 to 3.9) and with ad-replay at 0.2 or less. The classifier reads their imports (contracts, ad-script); history says they belong to the daemon's replay application. The half-finished extraction is real, but the fix is engine-boundary work in packages/ad-replay, not a file move.

Not collocation problems. The command-surface hubs (command-schema.ts 96.5, client-types.ts 88.9, cli-help.ts 85.7, cli.ts 71.8, agent-device-client.ts 63.4): adding a command touches registry, schema, help, client type and daemon handler by design; move 1 puts two hubs in one family, the shape stays. sdk (14 files, 0%) is the legacy alias surface CONTEXT.md gates for the next major: delete then, do not relocate now. contracts by design, as the issue says. core (14 files, k-NN 0%): the interactors co-change with the platform packages, but dissolving the rank-2 plugin registry is an ADR 0008 question. output-path.ts ↔ session-paths.ts: no co-change partner above 1.2, importers in five zones, no signal.

Sequence

1. PR A — move 1 plus batch-steps.ts. Pure move, tests carried unchanged.
2. PR B — move 2, with the four policy tables and baselines in the same commit.
3. PR C — move 3 plus client-metro-companion.ts, only if A and B measured as expected.

No behaviour change, no splits, no renamed exports, so the after-measurement is attributable to the move alone.

Measuring before and after

# before, on main at the merge-base
pnpm coupling --out .tmp/coupling/before.json
pnpm legibility --all --out .tmp/legibility/before.json   # seed 2677, reader condition
# after, on the PR head
pnpm coupling --out .tmp/coupling/after.json
pnpm legibility --all --out .tmp/legibility/after.json

Record in the PR description: overall reader / k-NN / majority; per-family rows for source, target and any family with n ≥ 20 that lost > 3 points; name-echo rate; Q, intra and cross share (all-time and 120-day); ≥5 share (expected −1.9 on A, +0.7 on B); the divergence list for the moved files, which should empty. Four Jev passes are under $0.30.

Decision rule. A move stays merged when: source and target families' reader accuracy moved the expected way and no family with n ≥ 20 dropped more than 3 points; Q did not fall and the ≥5 share did not rise more than 1 point (move 2's +0.7 is the accepted exception); check:layering, check:gate-manifest, lint, typecheck, format:check pass with no new allowlist entry and no ratchet slack spent. If move 1 comes back with cross share unchanged, the report's history model is not resolving renames; check scripts/repo-history/renames.ts first.

Stopgap probe until the report tooling lands (throwaway, not repo content)

Runs from the repo root against the gate's model, no network, no dependency. Pass a JSON { "path": "newFamily" } as the only argument for the what-if partition.

node --experimental-strip-types probe.ts               # baseline
node --experimental-strip-types probe.ts moves.json    # what-if

// Throwaway probe: k-NN placement divergence + co-change coupling, reusing scripts/layering.
import fs from 'node:fs';
import path from 'node:path';
import { execFileSync } from 'node:child_process';
import { listSourceFiles } from './scripts/layering/check.ts';
import { resolveImportEdges, targetDagZone } from './scripts/layering/model.ts';
import { workspaceSpecifierTargets } from './scripts/layering/package-boundaries.ts';

const repoRoot = process.cwd();
const movesArg = process.argv[2];
// moves: { "<file>": "<newFamily>" } — what-if relocation
const moves: Record<string, string> = movesArg ? JSON.parse(fs.readFileSync(movesArg, 'utf8')) : {};

const files = listSourceFiles();
const fileSet = new Set(files);
const sources = new Map(files.map((f) => [f, fs.readFileSync(path.join(repoRoot, f), 'utf8')]));
const edges = resolveImportEdges(sources, workspaceSpecifierTargets(repoRoot));

const familyOf = (f: string) => moves[f] ?? targetDagZone(f);

// ---------- import sets (value edges only) ----------
const importSet = new Map<string, Set<string>>();
for (const f of files) importSet.set(f, new Set());
for (const e of edges) {
  if (e.typeOnly || e.dynamic) continue;
  importSet.get(e.file)!.add(e.target);
}
// unresolved external specifiers: parse cheaply from source
for (const f of files) {
  const src = sources.get(f)!;
  const re = /^\s*(?:import|export)\s+(?!type\b)[^'"]*from\s+['"]([^'"]+)['"]/gm;
  let m: RegExpExecArray | null;
  while ((m = re.exec(src))) {
    const spec = m[1]!;
    if (spec.startsWith('.') || spec.startsWith('@agent-device/')) continue;
    importSet.get(f)!.add(`ext:${spec}`);
  }
}

function jaccard(a: Set<string>, b: Set<string>): number {
  if (a.size === 0 || b.size === 0) return 0;
  let inter = 0;
  for (const x of a) if (b.has(x)) inter++;
  return inter / (a.size + b.size - inter);
}

type Pred = { family: string; p: number; n: number };
const K = 5;
const knn = new Map<string, Pred>();
const nbr = new Map<string, Pred>();
const famCounts = new Map<string, number>();
for (const f of files) famCounts.set(familyOf(f), (famCounts.get(familyOf(f)) ?? 0) + 1);
const majority = [...famCounts].sort((a, b) => b[1] - a[1])[0][0];

for (const f of files) {
  const s = importSet.get(f)!;
  // neighbour vote
  const votes = new Map<string, number>();
  for (const t of s) if (!t.startsWith('ext:')) votes.set(familyOf(t), (votes.get(familyOf(t)) ?? 0) + 1);
  const nv = [...votes].sort((a, b) => b[1] - a[1])[0];
  const total = [...votes.values()].reduce((a, b) => a + b, 0);
  nbr.set(f, nv ? { family: nv[0], p: nv[1] / total, n: total } : { family: majority, p: 0, n: 0 });
  // knn
  const sims: Array<[string, number]> = [];
  for (const g of files) {
    if (g === f) continue;
    const j = jaccard(s, importSet.get(g)!);
    if (j > 0) sims.push([g, j]);
  }
  sims.sort((a, b) => b[1] - a[1]);
  // expand ties at the k-th similarity so tiny import sets do not pick neighbours by file order
  const kth = sims[K - 1]?.[1] ?? 0;
  const top = s.size < 3 ? [] : sims.filter(([, j], i) => i < K || j >= kth);
  const w = new Map<string, number>();
  let wt = 0;
  for (const [g, j] of top) {
    w.set(familyOf(g), (w.get(familyOf(g)) ?? 0) + j);
    wt += j;
  }
  const best = [...w].sort((a, b) => b[1] - a[1])[0];
  knn.set(f, best ? { family: best[0], p: best[1] / wt, n: top.length } : { family: majority, p: 0, n: 0 });
}

function acc(pred: Map<string, Pred>, subset: readonly string[] = files) {
  let ok = 0;
  for (const f of subset) if (pred.get(f)!.family === familyOf(f)) ok++;
  return subset.length ? ok / subset.length : 0;
}

// ---------- coupling ----------
const log = execFileSync(
  'git',
  ['log', '-M', '--name-status', '--format=COMMIT\t%H\t%ad\t%s', '--date=short', '--reverse'],
  { cwd: repoRoot, encoding: 'utf8', maxBuffer: 1 << 30 },
);
const renames = new Map<string, string>();
type Commit = { sha: string; date: string; subject: string; paths: string[] };
const commits: Commit[] = [];
let cur: Commit | null = null;
for (const line of log.split('\n')) {
  if (line.startsWith('COMMIT\t')) {
    const [, sha, date, ...rest] = line.split('\t');
    cur = { sha: sha!, date: date!, subject: rest.join('\t'), paths: [] };
    commits.push(cur);
    continue;
  }
  if (!cur || !line) continue;
  const parts = line.split('\t');
  const status = parts[0]!;
  if (status.startsWith('R') && parts[2]) {
    renames.set(parts[1]!, parts[2]);
    cur.paths.push(parts[2]);
  } else if (parts[1]) cur.paths.push(parts[1]);
}
const resolveMemo = new Map<string, string | null>();
function resolve(p: string): string | null {
  if (resolveMemo.has(p)) return resolveMemo.get(p)!;
  const seen = new Set<string>();
  let x = p;
  while (renames.has(x) && !seen.has(x)) {
    seen.add(x);
    x = renames.get(x)!;
  }
  const r = fileSet.has(x) ? x : null;
  resolveMemo.set(p, r);
  return r;
}
const firstTouch = new Map<string, Commit>();
const pairW = new Map<string, number>();
const pairS = new Map<string, number>();
let used = 0;
let skipped = 0;
const spanHist = new Map<number, number>();
const sinceDays = 120;
const cutoff = new Date(Date.now() - sinceDays * 86400e3).toISOString().slice(0, 10);
const pairWRecent = new Map<string, number>();
for (const c of commits) {
  const ids = [...new Set(c.paths.map(resolve).filter((x): x is string => x !== null))];
  for (const id of ids) if (!firstTouch.has(id)) firstTouch.set(id, c);
  if (ids.length > 60) {
    skipped++;
    continue;
  }
  if (ids.length < 2) continue;
  used++;
  const fams = new Set(ids.map(familyOf));
  spanHist.set(fams.size, (spanHist.get(fams.size) ?? 0) + 1);
  const w = 1 / (ids.length - 1);
  for (let i = 0; i < ids.length; i++)
    for (let j = i + 1; j < ids.length; j++) {
      const key = ids[i]! < ids[j]! ? `${ids[i]}\n${ids[j]}` : `${ids[j]}\n${ids[i]}`;
      pairW.set(key, (pairW.get(key) ?? 0) + w);
      pairS.set(key, (pairS.get(key) ?? 0) + 1);
      if (c.date >= cutoff) pairWRecent.set(key, (pairWRecent.get(key) ?? 0) + w);
    }
}
type Edge = { a: string; b: string; w: number; s: number };
const kept: Edge[] = [];
for (const [key, w] of pairW) {
  const s = pairS.get(key)!;
  if (s < 3) continue;
  const [a, b] = key.split('\n') as [string, string];
  kept.push({ a, b, w, s });
}
function modularity(es: readonly Edge[]) {
  const W = es.reduce((x, e) => x + e.w, 0);
  const inF = new Map<string, number>();
  const outF = new Map<string, number>();
  let cross = 0;
  for (const e of es) {
    const fa = familyOf(e.a);
    const fb = familyOf(e.b);
    if (fa === fb) inF.set(fa, (inF.get(fa) ?? 0) + e.w);
    else {
      cross++;
      outF.set(fa, (outF.get(fa) ?? 0) + e.w);
      outF.set(fb, (outF.get(fb) ?? 0) + e.w);
    }
  }
  const fams = new Set([...inF.keys(), ...outF.keys()]);
  let intra = 0;
  let expected = 0;
  const perFam = new Map<string, { inW: number; outW: number; Q: number }>();
  for (const f of fams) {
    const i = inF.get(f) ?? 0;
    const o = outF.get(f) ?? 0;
    const s = 2 * i + o;
    intra += i / W;
    expected += (s / (2 * W)) ** 2;
    perFam.set(f, { inW: i, outW: o, Q: i / W - (s / (2 * W)) ** 2 });
  }
  return { W, edges: es.length, crossShare: cross / es.length, intra, expected, Q: intra - expected, perFam };
}
const all = modularity(kept);

// per-file coupling profile
const fileIn = new Map<string, number>();
const fileOut = new Map<string, number>();
const filePartnerFam = new Map<string, Map<string, number>>();
for (const e of kept) {
  for (const [x, y] of [[e.a, e.b], [e.b, e.a]] as const) {
    const same = familyOf(x) === familyOf(y);
    if (same) fileIn.set(x, (fileIn.get(x) ?? 0) + e.w);
    else fileOut.set(x, (fileOut.get(x) ?? 0) + e.w);
    const m = filePartnerFam.get(x) ?? new Map();
    m.set(familyOf(y), (m.get(familyOf(y)) ?? 0) + e.w);
    filePartnerFam.set(x, m);
  }
}

// ---------- report ----------
const r2 = (x: number) => Math.round(x * 1000) / 10;
console.log(`files ${files.length} families ${famCounts.size} majority ${majority}`);
console.log(`majority ${r2((famCounts.get(majority) ?? 0) / files.length)}  nbr-vote ${r2(acc(nbr))}  knn ${r2(acc(knn))}`);
console.log(`commits used ${used} skipped(>60) ${skipped}; kept edges ${kept.length} cross ${r2(all.crossShare)}%  intra ${r2(all.intra)} expected ${r2(all.expected)} Q ${all.Q.toFixed(3)}`);
const multi = [...spanHist].filter(([k]) => k >= 2);
const multiN = multi.reduce((a, [, v]) => a + v, 0);
const ge5 = multi.filter(([k]) => k >= 5).reduce((a, [, v]) => a + v, 0);
console.log(`multi-family commits ${multiN}, >=5 families ${r2(ge5 / multiN)}%`);

console.log('\n## per family: files knn% Q out/in');
const rows = [...famCounts].map(([fam, n]) => {
  const sub = files.filter((f) => familyOf(f) === fam);
  const pf = all.perFam.get(fam) ?? { inW: 0, outW: 0, Q: 0 };
  return { fam, n, knn: r2(acc(knn, sub)), Q: pf.Q.toFixed(4), inW: pf.inW.toFixed(1), outW: pf.outW.toFixed(1), outIn: pf.inW ? (pf.outW / pf.inW).toFixed(1) : 'inf' };
});
rows.sort((a, b) => b.knn - a.knn);
for (const r of rows) console.log(`${r.fam.padEnd(20)} ${String(r.n).padStart(4)} ${String(r.knn).padStart(6)} ${r.Q.padStart(8)} in ${r.inW.padStart(7)} out ${r.outW.padStart(7)} out/in ${r.outIn}`);

console.log('\n## k-NN divergences (p>=0.6, n>=3), grouped by actual->predicted');
const div = files
  .map((f) => ({ f, ...knn.get(f)! }))
  .filter((x) => x.family !== familyOf(x.f) && x.p >= 0.6 && x.n >= 3);
const groups = new Map<string, typeof div>();
for (const d of div) {
  const key = `${familyOf(d.f)} -> ${d.family}`;
  groups.set(key, [...(groups.get(key) ?? []), d]);
}
for (const [key, ds] of [...groups].sort((a, b) => b[1].length - a[1].length)) {
  console.log(`\n### ${key} (${ds.length})`);
  for (const d of ds.sort((a, b) => b.p - a.p)) {
    const ft = firstTouch.get(d.f);
    const pf = filePartnerFam.get(d.f);
    const cp = pf ? [...pf].sort((a, b) => b[1] - a[1]).slice(0, 3).map(([k, v]) => `${k}:${v.toFixed(1)}`).join(' ') : '-';
    console.log(`  ${d.f}  p=${d.p.toFixed(2)}  nbr=${nbr.get(d.f)!.family}  cochange[${cp}]  first="${(ft?.subject ?? '').slice(0, 70)}"`);
  }
}

const FOCUS = [
  'src/daemon/replay/internal/',
  'src/cli-schema/',
  'src/screenshot-diff/',
  'src/sdk/',
  'src/metro/',
  'src/client/',
  'src/core/',
  'src/mcp/',
  'packages/capture-kit/src/recording/output-path.ts',
  'packages/host-kit/src/session-paths.ts',
  'packages/ad-replay/src/',
  'src/daemon/session-replay',
  'src/daemon/handlers/session-replay',
];
console.log('\n## focus files: knn / nbr / cochange partners');
for (const f of files) {
  if (!FOCUS.some((p) => f.startsWith(p))) continue;
  const k = knn.get(f)!;
  const pf = filePartnerFam.get(f);
  const cp = pf ? [...pf].sort((a, b) => b[1] - a[1]).slice(0, 4).map(([x, v]) => `${x}:${v.toFixed(1)}`).join(' ') : '-';
  console.log(`  ${f}  [${familyOf(f)}] knn=${k.family}/${k.p.toFixed(2)}/${k.n} nbr=${nbr.get(f)!.family} in=${(fileIn.get(f) ?? 0).toFixed(1)} out=${(fileOut.get(f) ?? 0).toFixed(1)} co[${cp}]`);
}

console.log('\n## top coupling hubs (out-family weight)');
const hubs = [...fileOut].sort((a, b) => b[1] - a[1]).slice(0, 15);
for (const [f, o] of hubs) console.log(`  ${f}  out ${o.toFixed(1)} in ${(fileIn.get(f) ?? 0).toFixed(1)} fams ${filePartnerFam.get(f)!.size}`);

console.log('\n## heaviest family pairs');
const fp = new Map<string, number>();
for (const e of kept) {
  const fa = familyOf(e.a);
  const fb = familyOf(e.b);
  if (fa === fb) continue;
  const key = [fa, fb].sort().join(' <-> ');
  fp.set(key, (fp.get(key) ?? 0) + e.w);
}
for (const [k, v] of [...fp].sort((a, b) => b[1] - a[1]).slice(0, 15)) console.log(`  ${k}  ${v.toFixed(1)}`);

// dump json for what-if diffing
fs.writeFileSync(
  path.join(path.dirname(new URL(import.meta.url).pathname), movesArg ? 'after.json' : 'before.json'),
  JSON.stringify({ knn: acc(knn), nbr: acc(nbr), Q: all.Q, intra: all.intra, cross: all.crossShare, perFam: rows, fileIn: [...fileIn], fileOut: [...fileOut] }, null, 1),
);

---

Generated by Claude Code

[thymikee]

Tooling landed on a branch — measurement notes for the collocation plan

The plan is directionally right and I'd merge its verdict shape: what-if re-labelling over the same commits, move 5 refused because co-change history contradicts the import classifier, and move 1 preferred over cli because rank 3 → 6 would be a back-edge for mcp (confirmed: cli-schema 3, commands 3, cli 6 in scripts/layering/model.ts:58-68). Four things in its measurement half need fixing before PR A/B/C start comparing numbers.

Where the tooling is. apex/module-shape-measures @ 86741f2be2 (pnpm coupling, pnpm legibility, the three *:test lanes). Most of the plan does not need a gateway key: pnpm coupling, pnpm repo-history:test, pnpm coupling:test and pnpm legibility:test all run offline, and pnpm legibility refuses without the key before making any request. Only the Jev rows need a key — I have one, so hand me base/head SHAs and I will post the before/after rows rather than have the plan carry unmeasurable claims. The branch lifts ai to 7.0.106 in the lockfile; 7.0.68 does not export experimental_evaluate.

1. Anchor the what-ifs to a tooling commit, not the probe. The probe and the reports disagree because they were computed on different trees and different rules. At a556e114cd (all-time / 120-day):

measure	value
commits used / skipped (> 60 files)	1,044 / 34 · 779 / 31
kept edges (support ≥ 3) · cross-family	6,314 · 4,061 (64.3%)
intra / expected / Q	36.5% / 11.5% / 0.250 · 0.282
median span · ≥ 5-family share	4 · 37.6% (39.6%)

2. The plan's Jev column is the old scrubbed condition. Under the corrected reader contract the same families are: commands 74.2% (k-NN 56.8, n=132), capture-kit 53.1 (60.5, n=162), daemon-server 49.0 (70.5, n=312), cli 19.0 (29.3, n=58), (root) 2.6 (11.8, n=76), cli-schema 37.5 (25.0, n=8), screenshot-diff 28.6 (14.3, n=7), client 63.6 (18.2, n=11), metro 14.3 (14.3, n=7), ad-replay 55.6 (0, n=9). So "watch commands stay ≥ 55% at n+8" is anchored ~19 points low — a collapse would read as success. Put the threshold near 70.

3. One k-NN definition. The probe reports capture-kit 25.9 / daemon-server 86.9 / commands 49.2 where the report says 60.5 / 70.5 / 56.8 — up to 35 points apart. "No family with n ≥ 20 dropped more than 3 points" is only checkable against a single definition, so take before and after from pnpm legibility rows, never from the probe.

4. Move 2 raises the reader number by construction. Publishing 53 root platform-runtime-* files under src/platform-runtime/ puts the family name into every import path that points at them, so reader accuracy and name echo both rise with no change in legibility. The echo caveat in the plan covers test basenames, not this. Judge move 2 by the (root) and platform-runtime rows, the echo rate, and the ablation gap — and state up front that the overall reader delta is uninterpretable. The move itself has real support: the model already misfiles 209 files into platform-runtime, mostly (root) (52), contracts (49), daemon-server (29), platform-apple (20).

One scope note: #2677 guard 9 keeps src/ and packages/ untouched, so PR A/B/C belong in their own issues — and they should rebase onto the tooling branch so the before/after is attributable to the move alone.

[thymikee]

Addressing the scope note and rebase ask from the comment above:

Own issue. Split "PR A" (move 1 + batch-steps.ts) out to #2679, and PR #2678 now targets that instead of this issue.

Rebase onto apex/module-shape-measures. Tried it — real conflict, not a mechanical one. That branch (86741f2) is 4 commits behind main, missing #2665 ("open --wait, flag suggestions, and refusals that name what to run"), which also touches src/cli/parser/command-suggestions.ts: apex has no suggestFlagFor/flag-suggestion code there at all, so the conflict can't be resolved by picking a side without either dropping this move's import-path fix for that file or pulling in unrelated feature work. PR #2678 stays on main for now (green, all local gates pass); I'll rebase it onto apex/module-shape-measures and add real pnpm coupling before/after numbers once that branch is refreshed against current main.

The other three measurement-methodology points (anchor to a tooling commit not the probe, the corrected Jev column, one k-NN definition) are noted for when PR B/C get planned against the refreshed tooling branch — Move 1's PR doesn't carry any Jev/coupling claims itself, so nothing to correct there yet.

---

Generated by Claude Code

[thymikee]

Follow-up evidence for the targeted forwarding/policy changes, checked against main at 788f2d305 after #3092, #3093 and #3094 merged. This is a structural edit-footprint check, not a new modularity measurement or a claim that a later feature already became cheaper.

Change	Owning seam now	Repeated production edit removed
Swift snapshot attributes	Copy-preserving RawAXNode operations	Three scope/fold constructors no longer enumerate semantic fields. git grep 'RawAXNode(' in Sources/AgentDeviceSnapshotPresentation finds three sites before #3092 and none after. Capture/conformance construction remains legitimate.
Android passive facts	Parser normalizes one explicitly typed record; presentation spreads it	Twelve individual builder assignments replaced by one ...node.passiveFacts; placement/actionability remain locally authored.
Native journal retention	Required retainsJournalResponseJson command trait	The journal's independent exhaustive command switch was deleted. Prepared dispatch retains its separate exhaustive routing decision.
Fold guidance	System family authors the topic; central help consumes it	Changing the shared fold restrictions no longer requires separately authoring a central help topic.

Proof: snapshot diff, native retention diff, family-owned help diff. All three merged with green applicable CI; snapshot preservation also had live iOS/Android evidence. Native CI executed all 278 host tests including the existing snapshot/screenshot journal-retention checks. These establish behavior and structure, not realized future change-coupling savings.

The next relevant feature should close the empirical loop using its normal diff, without adding tooling or artificial production attributes:

• New Swift semantic attribute: record the production-file count and confirm none of the three scope/fold projection modules needs field-forwarding edits.
• New Android passive attribute: confirm the presentation builder stays untouched; count contract/decoder/type edits separately from real new presentation decisions.
• New native command: confirm retention is declared with traits and the journal stays untouched; do not count genuinely distinct dispatch/runtime changes as avoidable forwarding.
• New fold restriction: confirm authored metadata/help changes stay in the system family, with central help only composing the topic. Continue authoring command-specific help in its family; the central module is now 987 lines.

Record the actual feature PR/SHA and before/after production-file footprint here when that change exists. The current evidence supports deleting forwarding obligations; it does not justify a universal field-policy table, prepared-route traits, or client-method derivation. Those were rejected because they add coupling, duplicate routing declarations, or introduce type-inference complexity.