| name | module-size-discipline |
| description | Use when planning tasks that touch big source files, when an edit would push a file past the module-size ceiling, when the pre-commit module-size ratchet warns or blocks, or when generating policies/module-size-baseline.txt. Operationalizes FR-25 — module-size ratchet (ceiling default 800; over-ceiling files may shrink, never grow; extraction along a responsibility seam is in-scope, not scope creep). Do NOT use for docs/markdown size (FR-23 owns docs), to force decomposition of an existing monolith (that is its own explicit ticket), or to judge split quality by regex (seam-vs-mechanical is semantic — code-review owns it). |
| source_inspiration | conceptual-only |
| license_status | clean-room-original |
| fusebase_flow_version | 3.16 |
| risk_level | medium |
| invocation | automatic |
| expected_outputs | ["per-task target-file declarations (tasks.md) with extraction-or-exemption for over-ceiling targets","extraction into a new module along a responsibility seam, or an explicit exemption","policies/module-size-baseline.txt via agent-run --write-baseline (on the operator's chat go-ahead)"] |
| related_workflows | ["greenlight-implement.md","verification-gate.md","lightweight-lane.md"] |
| hook_dependencies | ["hooks/git/pre-commit (module-size step)"] |
Module-Size Discipline (FR-25)
Purpose
Stop source files from accreting into monoliths nobody (human or agent) can load in one pass. Source in a Flow workflow is AI-read (FR-22/FR-24 audience principle): a 19k-line file forces slice-reads on every future session. Monoliths are the integral of N individually-reasonable diffs — no single diff is ever flagged — so the framework gates the accumulating dimension deterministically (line count is objective, unlike FR-22/FR-23 semantics) and steers extraction at plan- and write-time.
The ratchet (deterministic gate)
Config: policies/module-size.yml (ceiling default 800 · source_globs · exempt_globs · baseline_file · enforcement · gitignored module-size.local.yml override). Engine: hooks/shared/module_size.py, wrapper hooks/local/check-module-size.sh, wired into hooks/git/pre-commit.
| Case | Verdict |
|---|
| Gated file NOT in baseline, lines ≤ ceiling | pass |
| NOT in baseline, NEW over ceiling (crosses the ceiling in this change) | BLOCK — extract, or adopt (--write-baseline) |
NOT in baseline, PRE-EXISTING over ceiling (over ceiling at HEAD), touched/shrunk in a change gate (--staged/--worktree, not growing) | pass — the refactor path (delta-aware adoption grace) |
| NOT in baseline, PRE-EXISTING over ceiling, GROWN | BLOCK — a monolith may be touched/shrunk, never grown |
Any over-ceiling not-baselined file under --all (audit) | reported (absolute; no HEAD delta) — tells you what to adopt |
| Baselined file, lines ≤ its baseline value | pass (shrinking/holding is always fine) |
| Baselined file, lines > its baseline value | BLOCK — over-ceiling files may not grow |
File matches exempt_globs | never gated |
No baseline_file committed | warn-only + generation instruction (adoption-safe) |
Modes: --staged (pre-commit default) · --worktree (vs HEAD; optional Stop-hook wiring) · --all (full scan; also a CI step in fusebase-flow-verify.yml) · --write-baseline (agent-run on the operator's chat go-ahead — freezes current over-ceiling files; the agent commits the result; presence switches warn → block) · --write-baseline <path> (re-keys ONE row — the targeted refresh; a full regen grandfathers every current violation, so prefer the single-file form).
Baseline shipping: the template ships its own committed baseline (Flow's own over-ceiling files), so the gate is live from commit #1 on greenfield instantiations. Installing into an existing repo with pre-existing monoliths: those files are not hard-blocked on first touch — the delta-aware change gate lets you touch/shrink a pre-existing over-ceiling file (only NEW-over-ceiling files and growth block). To freeze them at their current size (so future growth is caught against a recorded value, and to clear the --all audit), the agent runs --write-baseline once on the operator's chat go-ahead — it auto-mints a single-use FR-07 approval for the protected baseline path, and the agent then commits and consumes it (the sanctioned path; never --no-verify). The operator approves adoption in chat; they run no terminal command.
Local override (policies/module-size.local.yml, gitignored) is additive-only: it may append exempt_globs / source_globs entries; enforcement, ceiling, and baseline_file cannot be overridden locally (a gitignored kill switch would disarm the gate invisibly). The engine prints a notice whenever a local override is active.
Rename tripwire: the baseline keys by path — after renaming a baselined over-ceiling file, its first content edit blocks (fail-closed, zero-growth included) until it is re-keyed — the agent runs --write-baseline <new-path> on the operator's go-ahead (and the old row disappears on the next targeted or full refresh; stale rows for absent files are inert).
Plan-time rule (where the problem starts)
In implementation-planning / tasks.md: every task names its target file(s). A task targeting an over-ceiling file must either (a) extract the addition into a new module, or (b) carry a one-line exemption with reason. "Where does this code live" is a cheap question at Plan and a never-asked question mid-implement.
Write-time rule (AI Developer)
- An edit that would push a gated file over the ceiling, or grow an already-over-ceiling file → extract along a responsibility seam (a nameable concern), not a mechanical
utils2.ts split.
- That extraction is in-scope for the task: it is NOT scope creep and NOT by itself an FR-21 promotion trigger. (FR-21 interplay — see
lightweight-lane.)
- Never bypass with
--no-verify (FR-06). Remedies: extract, or surface the exemption question to the operator (FR-19).
Exemptions (deliberate, reviewable)
Justified monolith classes go in exempt_globs: generated code (SDK/OpenAPI output), lockfiles, vendored complete-file mirrors, data-as-code catalogs/fixtures, migrations. Exemption is a policy edit the operator sees — never silent.
What this skill does NOT do
- No forced refactor: existing monoliths freeze at baseline; decomposition is its own (usually Full-lane) ticket with its own risk assessment.
- No split-quality regex: seam-vs-mechanical is semantic —
code-review checks it by reading.
- No docs gating: artifact/doc size is FR-23's axis.
Anti-patterns
- Splitting mechanically to satisfy the gate — observable criterion: an extraction landing in a file whose name does not state a responsibility (
utils2, helpers2, misc, extra, more-style names) is a review blocker; a named seam is judged by reading.
- Raising the baseline to make a violation pass — adoption needs the operator's explicit go-ahead (given in chat), never the agent's own initiative to dodge a block; on that go-ahead the agent runs
--write-baseline (prefer the single-file form so refreshes are never global amnesties). The guard is the operator's decision, not making the operator type the command.
- Treating the ratchet warning as noise in warn-only mode — surface it to the operator with the activation instruction instead.
- Adding
exempt_globs entries for ordinary source because extraction is inconvenient.
Clean-room note
Original Fusebase Flow content. Ratchet-style size gating is common public CI practice (grandfathering + no-growth baselines); no third-party code, prompts, skill files, or hook scripts are copied. See docs/source-map.md.
