source: .forge/design/harness/file-size-check.md · generated — edit the markdown, not this file

A size limit on source files, enforced by a test — Design

Status: approved by the lead, Tharinda Rajapaksha, on 2026-11-12, after two fresh-context review passes; revised the same day (Rev 1, § Revisions) to count code lines and to hold every file to the limit. In force when the implementation PRs (D-8), reviewed as each repository requires, merge (.claude/CLAUDE.md § Reference Map, harness design records). Author: Tharinda Rajapaksha Date: 2026-11-12 Scope: in each app repo, one unit test that holds its own list — forge-et-be src/test/groovy/com/empireteas/arch/FileSizeSpec.groovy; forge-et-fe and forge-et-pwa src/app/fileSize.test.ts — and the repo’s CLAUDE.md (its section on what the build and tooling enforce). In the harness: .forge/design/coding-standards.md §1 and §7.1, .claude/agents/backend-reviewer.md, .claude/agents/frontend-reviewer.md, .claude/agents/plan-reviewer.md, .claude/agents/backend-implementer.md, .claude/agents/frontend-implementer.md, and .forge/owed.md. No workflow, ruleset, hook or test-selection change; no CI minutes and no AWS cost.

Context

On 2026-11-12 the lead decided to split the three largest backend classes now, as feature F45 (.forge/specs/F45-split-large-backend-classes-spec.md), and the three largest CRM screens as a work item of their own (.forge/owed.md). The code review of 2026-11-08 that raised them found no defect behind the size: each file grew one reasonable PR at a time, with nothing to say when it had grown too far. Splitting them once does not stop the next file growing the same way. The lead asked the same day for a rule, and a mechanism behind it, so that the harness prevents this instead of a review finding it later, and then asked for one limit, chosen from the code, that existing code, future code and open PRs all meet.

Nothing limits a file’s size today: .forge/design/coding-standards.md, the reviewer agents and plan-reviewer say nothing about it, and no app repo has a check (git grep -n -i -E 'max-lines|maxLines|FileLength|noExcessiveLines' origin/main in each returns nothing, 2026-11-12).

How the code was measured (2026-11-12; forge-et-be bb9fe28e, forge-et-fe 26e4cd42, forge-et-pwa 3a378122; source files as D-2 defines them). Each file was counted two ways: total lines (wc -l), and code lines (D-1).

Repo Files Comment and blank share Code lines: median · p95 · p99 · largest Over 600 code lines Over 800 code lines Over 800 total lines
forge-et-be 1,431 47% 23 · 213 · 424 · 1,960 7 5 11
forge-et-fe 758 26% 76 · 478 · 805 · 1,751 21 8 19
forge-et-pwa 18 39% 23 · 66 · 66 · 66 0 0 0

A rule on its own would not have held: each PR that grew these files was reviewed, and no single PR looked like the one that went too far. So the check records each file’s size, which makes visible the growth a reviewer cannot see in one diff.

Decisions

D-1 — The limit is 800 code lines per source file, in every app repo. A code line is a line that still holds something other than whitespace once comments are removed: // line comments, /* */ block comments and Javadoc, but never text inside a string, character or template literal or a Java text block. Blank lines do not count. The reasons, from the measurements above:

  • Code lines, not total lines. Comments and blank lines are 47% of the backend’s lines and 26% of the CRM’s, because the backend writes its reasons into Javadoc as coding-standards.md §9 asks. A total-line limit would be about twice as strict on backend code as on frontend code, and would reward deleting documentation. It also points at the wrong files: mailbox/MailboxProvider.java is 1,660 lines in total but 590 code lines — the documented records the seam returns — while features/email/templates/TemplateEditorForm.tsx is 961 lines in total and 805 of them are code.
  • 800, not 600 or 1,000. At 800, the files over the limit are the clear outliers: 5 backend files and 8 CRM files, against a p99 of 424 and 805 code lines. Each one is a file a reader cannot hold in mind, and all 13 can be split as planned work (D-8). At 600, 28 files would have to be split, many of them CRM screens that other features are changing now; at 1,000, files twice the size of the CRM’s p95 would pass.
  • One number. The same limit applies to new code, to existing code and to every open PR, and to the classes F45 and the other planned splits create (F45 FR-8 follows it — § Revisions). A change to the figure is a revision to this design, with the lead’s decision.

D-2 — What counts as a source file. forge-et-be: every .java file under src/main/java. forge-et-fe and forge-et-pwa: every .ts and .tsx file under src that is not a .d.ts file and not test code, test code being what the repo’s own .dependency-cruiser.cjs rule no-fixture-in-non-test excludes in its pathNot (both frontends carry the same one; forge-et-fe’s shadcnOnly.test.ts copies it the same way). Test code is not counted (What it does not cover).

D-3 — A unit test in each app repo, not a lint rule or a CI step. forge-et-be: FileSizeSpec, a Spock spec in the arch package. forge-et-fe and forge-et-pwa: src/app/fileSize.test.ts, a Vitest test. Each reads the files from disk, so it runs in milliseconds and needs no server.

  • How it counts code lines. The frontend tests count with the TypeScript scanner (the typescript-classic package shadcnScan.ts already uses), skipping comment trivia. The backend spec counts with a small tokenizer that knows Java’s string and character literals, text blocks, line comments and block comments. Each counter is pinned by fixed example sources in the test (a // inside a string, a /* inside a text block, a comment after code on the same line), so it cannot drift unseen.
  • It runs on every PR’s record, whatever the change. forge-et-be’s scripts/select-tests.py always runs com.empireteas.arch.*. In both frontends, scripts/test-selected.mjs adds to every selection each test whose text reads files (READS_FILES, scanAlwaysRun), so the test must read the tree with readdirSync and readFileSync, which that pattern matches.
  • A failing test blocks the merge with no workflow change. The records record nothing when a test fails (forge-et-be scripts/local-build-evidence.py, the frontends’ scripts/local-test-evidence.mjs behind pnpm test:record), so the PR has no Test record check.
  • Why not a lint rule. The frontends’ Biome (2.6.6) has style/noExcessiveLinesPerFile, and per-path overrides could cap each listed file, but it counts lines rather than code lines (D-1), it cannot fail when a listed file shrinks and its count is left unchanged or when an entry is left behind (D-4 rules 3 and 4), it would put the list in biome.jsonc, and the backend has no equivalent (it runs Spotless and Error Prone, no Checkstyle — coding-standards.md §7.9).
  • Why not a CI step. It would need the lead’s approval for a pipeline change and would run in one place only.

D-4 — The files still over the limit are listed in the test, each with a planned split, and the list only empties. Each test holds, as a constant sorted by path, the files over the limit when the check lands, each with its code-line count and the .forge/owed.md row or feature that splits it. It is a list of known breaches on their way out, not a list of exceptions: every file on it has planned work that brings it under the limit (D-8), and nothing is ever added to it. The list is not a separate file, because a separate file would cost a full run on every edit: forge-et-be treats src/test/resources/** as shared code (scripts/shared-code.json), which runs every backend test, and in forge-et-fe a file in src/app outside the test files is a browser-gate input, which makes pnpm e2e:gate --selected a full gate (scripts/browser-gate/gate-inputs.json, select.mjs). A change to the test file itself costs neither. The test fails when:

  1. a file not on the list is over 800 code lines;
  2. a listed file has more code lines than its recorded count (it grew);
  3. a listed file has fewer code lines than its recorded count: the count comes down to the new figure in the same PR, so the lines removed cannot be added back later;
  4. a listed file is at or under 800 code lines, or no longer exists: its entry is removed;
  5. the list is not sorted, or names a file twice.

A rule 3, 4 or 5 failure message prints the corrected list in the form the test holds it, so the person or agent fixing it copies the lines the message gives. A rule 1 or 2 failure message prints no list: it names the file and its count and says the code must be split by job (D-6). The first list is produced by running the test with a generate switch (an environment variable the test reads), which prints the whole list for the tree; that switch is used once, in each repo’s check PR, and is then removed.

Moving a file. A rename or move of a listed file with no other change carries its entry, at the same count, to the new path; the reviewer confirms it is a move (git diff -M --stat shows the rename) and records that in the review.

Two PRs that shrink the same file both change its line in the list, so the second to merge has a conflict there. It is resolved by merging main in and taking the count the test’s message gives.

When the last planned split merges, the list is empty and the test keeps only rule 1.

D-5 — No exceptions. A change that would take a file over the limit, or grow a listed file, moves code out by job instead (D-6): the new code goes into a new class or module, or the PR extracts at least as many code lines as it adds. No reviewer may allow an entry or a higher count, and no file type is exempt: there are no generated or vendored files under the scanned paths today, and if one is ever needed, its exclusion is a revision to this design with the lead’s decision. Until a listed file’s planned split lands, a defect fix in it offsets its own growth, which is one more reason to schedule the splits early (D-8).

An implementer agent never adds an entry or raises a count. It lowers a count or removes an entry when the test says to (rules 3 and 4), carries an entry on a pure move, and splits the code when a change would grow a file past the limit; when it cannot see how to split it, it reports that as an open question in its hand-off.

D-6 — A rule in the coding standards, said where code is written. coding-standards.md §1 (feature-first placement) gains one paragraph: a source file holds at most 800 code lines (D-1’s definition); before a change takes a file past that, the code is split by job into classes or modules in the same feature package or folder, never into a general-purpose helper class; the test enforces it. §7.1 (the enforcement ladder) names the test. The implementer agents (backend-implementer, frontend-implementer) carry D-5’s implementer rule.

D-7 — The reviews see it before the test does.

  • plan-reviewer gains a check: a plan whose ## Files to Modify adds code to a listed file, or to a file within 100 code lines of the limit, says where the new code goes (a new class or module, named) and how the file stays under the limit. It reads the list from the test file, and a file’s count by running the test’s counter or, as a first look, from git -C <repo> show "origin/main:<path>" | wc -l, which is at most one lower than the code-line count (when the last line has no newline). A plan that would take a file past the limit is a Blocker; a plan that adds code to a file near it with no such line is an Important.
  • backend-reviewer and frontend-reviewer each gain a numbered dimension: a diff that would fail the test is a Blocker (the test will stop it anyway, so the review names the split); a diff that takes a file within 100 code lines of the limit with code that has a separate job is a Nit, or an Important when the file had ten or more non-merge commits in the 60 days before the PR (git log --no-merges --since=60.days --oneline origin/main -- <path> | wc -l); a change to the list is only ever a rule 3, rule 4 or move change.

The 100-line margin brings the files between 701 and 800 code lines to the reviewers’ attention (1 in forge-et-be and 8 in forge-et-fe on 2026-11-12) before they reach the limit.

D-8 — The rollout, and every file brought under the limit.

  1. One harness PR carries the standards paragraph, the agent changes and an owed.md row per app repo.

  2. One PR per app repo adds the test with its list and the paragraph in the repo’s CLAUDE.md section on what the build and tooling enforce; each gets its review record as any app-repo PR does. Just before each merges, main is merged into it and the list regenerated, because counts are exact and the frontend changes daily: a list generated earlier would be wrong on main. That is a reason to merge main that .claude/rules/git-conventions.md § Branching accepts (main changed something the PR’s tests rely on). A frontend check PR changes only test files and its repo’s CLAUDE.md, so its change selects no browser spec: it records Selected browser run: none selected and does not run the gate (.forge/design/harness/fewer-nightly-reds.md R-1). The list for forge-et-pwa is empty, so its test only stops the first file from passing the limit. A file over the limit at generation that item 3 does not name gets an owner before the check PR merges: a line added to the .forge/owed.md row “Split the other source files over the limit”, with the lead’s decision; otherwise the check PR waits until the PR that pushed the file over has split it. The forge-et-fe check PR merges after forge-et-fe#493, which changes AccountFormPage.tsx and EmailRoute.tsx, so that #493 is not made to split screens the CRM-screen split will take apart once it has merged.

  3. Every file over the limit has planned work that splits it. On 2026-11-12 the 13 are:

    • F45: mailbox/GraphMailboxProvider.java (1,960 code lines), mailbox/LocalMailboxProvider.java (1,212) and lead/service/LeadService.java (886);
    • the .forge/owed.md row “Split LocalLiveMailbox after F45”: mailbox/LocalLiveMailbox.java (889);
    • the .forge/owed.md CRM-screen row: features/email/compose/ComposeEmailDialog.tsx (1,751), features/accounts/AccountFormPage.tsx (1,151) and features/leads/LeadFormDialog.tsx (1,058);
    • the .forge/owed.md row “Split the other source files over the limit”: mailbox/service/EmailSendService.java (1,064), features/attachments/RecordAttachmentsPanel.tsx (1,018), features/activities/FollowUpEditBody.tsx (961), features/notesAndTags/RecordNotesSection.tsx (903), features/accounts/AccountListScreen.tsx (852) and features/email/templates/TemplateEditorForm.tsx (805).

    Since 2026-11-14 the files of the three .forge/owed.md rows are split by feature F46 (.forge/specs/F46-split-files-over-size-limit-spec.md). Their current counts, and which are done, are kept in .forge/design/harness/file-size-progress.md. Each lowers or removes its entries as it shrinks the files (rules 3 and 4). When a split has merged before its repo’s check PR, its files are not listed. Because F45 AC-11 requires each move commit to change nothing else, a list edit in an F45 PR is a commit of its own; lowering a count or removing an entry is a test change F45 AC-2 and NFR-1 allow, which F45’s spec records (its Rev 1).

D-9 — Open PRs and work in flight. A branch does not have to be up to date with main to merge, so a branch cut before the check lands does not run it. Its review applies D-7. The day each app-repo check PR merges, the team is told, and the author of every open PR in that repo that changes a source file merges main in and runs its record again before merging, so the open PR meets the limit too. If one merges without doing so, the next test run on main, or on any branch that merges main — the nightly full run at the latest — fails if it grew a listed file, took a file past the limit, or shrank a listed file without lowering its count. That failure is handled like any red night (a nightly-red issue, fixed before new work starts), and the author of the PR that caused it fixes it with a split or the list change the test gives.

What it does not cover

  • Test code. A spec reads as a list of cases, and a cap would split specs at an arbitrary case rather than by job; large specs are left to review. A cap on tests can be added later with its own figure.
  • e2e/ support code and scripts/. Outside D-2’s scope: for example forge-et-fe’s e2e/browser/size-matrix/arrange.ts, forge-et-be’s scripts/local-build-evidence.py and forge-et-pwa’s scripts/local-test-evidence.mjs are each over 800 lines on 2026-11-12.
  • The size of a method or a component. A file under the limit can still hold one 300-line method. That stays a review finding.
  • Whether a split is by job. The test sees only line counts. Splitting a file into PartOne/PartTwo meets the limit and misses the point; the review (D-7) and the standards paragraph (D-6) are the control.
  • The harness’s own scripts and documents, which have no such check.

Verification, for each implementation PR

  • The test passes on the PR’s head, with the list it prints for that head.
  • The counter’s fixed examples pass: a // inside a string, a /* inside a text block or template literal, a comment after code on the same line, a Javadoc block, and a blank line each count as the test says.
  • forge-et-fe and forge-et-pwa: on a change to documentation only, the selection lists src/app/fileSize.test.ts (pnpm test:selected --list), so the always-run set includes it.
  • A probe file over 800 code lines → the test fails and names it; removed.
  • A listed file grown by one code line → the test fails with “grew”; reverted. A comment added to it → the test still passes.
  • A listed file shortened, its count unchanged → the test fails and gives the count to write; reverted.
  • An entry for a file at or under the limit → the test fails with “remove”; reverted.
  • A listed file renamed with its entry carried → the test passes; reverted.
  • The repo’s own checks (./gradlew check, or pnpm check and pnpm typecheck) → exit 0.

Revisions

  • Rev 1 — 2026-11-12 (the lead, Tharinda Rajapaksha). The lead asked for one limit chosen from the code and held everywhere — existing code, future code and open PRs. After measuring both repos two ways (§ Context): the limit now counts code lines, not total lines (D-1); the list holds only files with a planned split and never grows (D-4); reviewer exceptions are removed (D-5); every file over the limit is named with the work that splits it (D-8 item 3), adding TemplateEditorForm.tsx and leaving out MailboxProvider.java (590 code lines); open PRs merge main in and meet the limit once the check lands (D-9); reviewer severities follow (D-7). F45’s FR-8 and AC-8 are revised to the same rule in the same PR.

Generated from .forge/design/harness/file-size-check.md by .claude/lib/render-docs-html.js. Markdown is canonical.