Code Organisation — how the tree is laid out and kept tidy — Design Spec
Milestone: code-organization Manual: docs/contributor_manual/swiftui-development-standards.md — the “File Organization & Size Guidelines” section carries the Swift half for contributors;
backend-development-standards.mdgets a matching “Where a module lives” section when Step 1.1 lands. No user-manual section: this is a contributor rule set.Status: APPROVED by the owner 2026-11-14 (the six rulings in the last section folded into the bullets they decide; owner request 2026-11-14: a spec for how the code is organised and kept tidy, and a review of the tree against it; the review is
agent-work/reviews/code-organization-review-2026-11-14.md, the first-wave briefsagent-work/briefs/code-org/). Tags: [OK] built and enforced · [PARTIAL] a guard exists, the rule is wider than it checks · [GAP] a rule with no guard. Issues: #1944 (folders), #1945 (dead files), #1941 (Xcode registration), #4446 (lint ratchet), #1915 (comment hygiene), #3040 (shell size), #2569 (routes grouping), #2566 (engine package reorg), #6318 (--sinceguards).Scope with other docs:
AGENTS.md“Where Things Live” stays the short rule for agent scratch and the repo root; this spec is the long form for product code and the one the guards cite.design/swiftui-app-reorg.md(2026-07) andagent-work/design/engine-package-reorg.md(2026-07) are the surveys this spec grew from; their shim strategy is superseded byAGENTS.mdrule 0 (a move is a hard cutover in one commit, never an alias module).
Intent
A contributor or an agent who knows one feature finds its code in one place, names tell what a file holds before it is
opened, nothing in the tree is unreachable, no file is too big to review, and every one of these holds by a guard that
runs on the builder, not by a sweep: the files a batch adds or moves are judged in that batch, the tree’s old debt nightly. Two trees: the SwiftUI app under fichero/fichero with its tests under
fichero/Tests, and the Python engine under fichero-server/src/fichero_server with its tests under
fichero-server/tests (the CLI, MCP and Builder packages follow the same rules). Measurements in this spec are from
2026-11-14 at 7438dd2f5d.
Prior art (reuse, do not invent)
- Feature folders, not layer folders, for SwiftUI: Apple’s sample apps and the SwiftUI community put a feature’s
views, its view-local state and its previews together; shared layers stay small. The app already does this under
Views/<Feature>/;Models/andServices/are the two layer folders that outgrew the pattern. - One type per file,
Type+Topic.swiftfor extensions: the Swift API design guidelines and SwiftLint’sfile_types_order/file_namerules; the app’sContentView+*.swiftfamily is the local example. - Python src layout and PEP 8 module names:
src/<package>/<domain>/<module>.py,snake_case, a module named for what it does; tests mirror the package tree (pytest’s convention and the engine’s owntests/unit/<package>/). - Dead code by tool, not by eye:
peripheryfor Swift (whole-project, needs an index build, so nightly),vulturefor Python (static, seconds, so per batch), jcodemunchfind_dead_codefor the import graph, and the repo’s owncheck_dead_files.py. The existing guard’s blind spot (a file reached only through an extension) is why the adopted tools are the rule and the home-made scanner is the floor. - Ratchets, held exactly:
check_swiftlint_warning_ratchet.py(#4446),check_coverage_ratchet.py(#4249),check_release_size_ratchet.py(#4444): a committed baseline, a count that may never rise,--update-baselineas a decision. The compiler-warnings ratchet below copies that shape.
What exists today (measured 2026-11-14)
| Concern | Guard | Runs | Notes |
|---|---|---|---|
| Catch-all Swift folders | scripts/check_folder_organization.py |
per batch | >18 loose files in one folder, or a named mixed-concern folder; 8 known offenders |
| Dead Swift files | scripts/check_dead_files.py |
per batch | primary type referenced nowhere else; 18 known candidates, 5 of them false positives (extension-only files) |
| Swift file in the target | scripts/check_xcode_registration.py |
per batch | synchronized root, so a file on disk compiles; catches membershipExceptions |
| Shell file size | scripts/check_shell_chrome.py rule 3 |
per batch | ContentView* / Sidebar* ≤ 1000 lines, no allowlist |
| SwiftLint sizes | .swiftlint.yml, fichero/.swiftlint.yml |
per batch (errors) | file 400 warn / 1000 error; type 250 / 500; function 50 / 100; line 140 / 200 |
| SwiftLint warnings | scripts/check_swiftlint_warning_ratchet.py |
--since per batch; whole tree nightly |
baseline 123 in scripts/swiftlint_warning_baseline.json; harness.toml since_guards |
| Per-file lint ratchet | fichero-builder/fichero_builder/lint.py |
ready check, per batch | swiftlint and ruff by rule per touched file against the base; a new file must be clean |
| Python lint | ruff.toml (E4 E7 E9 F) |
per batch | error-only set, zero tolerance; no warning class to ratchet |
| Commented-out code | scripts/check_comment_hygiene.py, scripts/check_python_comment_hygiene.py |
per batch | 3+ code-like comment lines; TODO must cite an issue |
| Duplicate handlers | scripts/check_duplicate_paths.py |
per batch | same METHOD+PATH twice, two KG row writers |
| Compiler warnings (Swift) | none | — | the build rung keeps error: lines only (check_tool.py) |
| Type checking (Python) | none | — | no pyright or mypy anywhere in the repo |
| Dead Python | none | — | no vulture; jcodemunch find_dead_code is advisory |
Behaviours
A. Folders
code-org.folders.root[OK] — The repo root holds governance docs (AGENTS.md,CLAUDE.md,CONSTITUTION.md,CONTRIBUTING.md,README.md,USER.md,CHANGELOG.md,RELEASE_NOTES.md,LICENSE,LICENSING.md,NOTICE,CLA.md,CODE_OF_CONDUCT.md), repo-wide config (mkdocs.yml,features.yaml,harness.toml,ruff.toml,.swiftlint.yml,coverage-baseline.json,requirements-docs.txt,.python-version) and the product and tooling directories (fichero/,fichero-server/,fichero-cli/,fichero-mcp/,fichero-builder/,scripts/,docs/,agents/,agent-work/,test-fixtures/,icons/,web/,pipeline/until its removal). Nothing else: a new file at the root is misplaced. Not built:AGENTS.mdlists the rule, no guard reads the root (#1944; issue to file under this milestone). Test (to write): guardcheck_repo_rootwith the allowlist above and a--self-test. Test: fichero-server/tests/unit/scripts/test_check_file_placement.py (check_file_placementwhole-tree mode, baselined in KNOWN_VIOLATIONS;--sincejudges each new file).code-org.folders.swift-layers[OK] — The app has five top-level folders underfichero/fichero:App/(lifecycle, windows, menus,AppState),Models/(stores and domain types),Services/(engine clients and manual services),Intents/(App Intents and AppleScript entry points),Views/(the UI), plusResources/. A sixth is a ruling. Test: fichero-server/tests/unit/scripts/test_check_folder_organization.py (the scan floor names the tree).code-org.folders.swift-feature-folders[PARTIAL] — UnderViews/a feature’s files live inViews/<Feature>/, with subfolders when a feature passes 18 loose files (Views/Library/ViewModes/Canvas/2D/is the shape). A folder holds one feature; a folder named for a layer (Views/Models/) or for a single file is wrong. Built: the 18-file limit and two named mixed-concern folders (#1944). Not built: a single-file folder check and the layer-name check. Test:scripts/check_folder_organization.py.code-org.folders.swift-models-services-by-feature[GAP] —Models/andServices/carry one subfolder per feature (Models/Segments/,Services/Pairing/), named as the matchingViews/<Feature>/; the flat root of each holds only cross-feature types. Today 355 and 220 files sit flat; both are known offenders of the 18-file rule since #1944 and the guard’s allowlist lets them grow. Test:scripts/check_folder_organization.pyonce the two entries leave itsKNOWN_VIOLATIONS. Was: the allowlist let them grow; now eachKNOWN_VIOLATIONSentry carries its file count at baseline (355 and 220) and the guard fails when a count rises.code-org.folders.swift-view-local-state[OK] — A view’s own@Observablestate (a*State,*ModelorFocused*type used by one feature) sits BESIDE its views inViews/<Feature>/;Models/<Feature>/holds shared state, read by two or more features (ruled by the owner 2026-11-14). Today 38 observable types sit underViews/; the guard names the ones a second feature reads (#1944). Built:check_folder_organizationreports an@Observable/ObservableObjecttype underViews/<Feature>/that anotherViews/<Other>/orApp/reads, with “→ Models// (read by two features)”; today’s 18 are baselined ( KNOWN_SHARED_STATE), new ones fail,--listnames them. Test: fichero-server/tests/unit/scripts/test_check_folder_organization.py;check_folder_organization --self-test.code-org.folders.swift-test-mirror[OK] —fichero/Tests/Unit/<platform>/<Layer>/<Feature>/mirrorsfichero/fichero/<Layer>/<Feature>/,Tests/UI/<platform>/<Feature>/the surfaces; a test ofViews/Segments/goes underTests/Unit/general/Views/Segments/. Shared helpers (TestFixtures.swift,AppSource.swift,EngineHarness.swift) sit atTests/Unit/general/root. Built: the tree has the shape; 437 model tests sit flat becauseModels/is flat. Built:check_folder_organizationreports a test folderTests/Unit/<platform>/<Layer>/<Feature>/with no app folder to mirror (today 2, baselined inKNOWN_TEST_ORPHANS). Test: fichero-server/tests/unit/scripts/test_check_folder_organization.py;check_folder_organization --self-test.code-org.folders.python-packages[OK] — Engine code lives in one domain package underfichero-server/src/fichero_server/:api/(routes by resource underapi/routes/<resource>/, transport, startup),models/,db/,core/(small utilities with no domain),llm/,media/,formats/,importers/,knowledge/,workflows/(+tools/),recipes/,execution/,training/,security/,transfer/,remote_read/,finddocs/,checking/,actions/,mcp/. The package root holds__init__.py,__main__.pyand nothing else. Built: the packages exist (#2566, #2569). Not built: 18 modules still sit loose at the root (export_service.py,histdate.py,sync_folder.py…) and nothing refuses a new one. Test (to write): guardcheck_engine_package_layout, root allowlist of two files. Test: fichero-server/tests/unit/scripts/test_check_file_placement.py (check_file_placementwhole-tree mode, baselined in KNOWN_VIOLATIONS;--sincejudges each new file).code-org.folders.python-no-shim-modules[OK] — A moved module leaves nothing behind: nofrom new import *plus asys.modules[__name__]alias (AGENTS.mdrule 0). Today 18 such modules sit underapi/routes/(kg_*.py,folders.py,search_explain.py, all “Moved to … (#2569)”),api/main.pyimports 17 of them and 31 other files the rest. Test (to write):check_engine_package_layoutrefuses a module whose body assignssys.modules[__name__]. Test: fichero-server/tests/unit/scripts/test_check_file_placement.py (check_file_placementwhole-tree mode, baselined in KNOWN_VIOLATIONS;--sincejudges each new file).code-org.folders.python-test-mirror[OK] —fichero-server/tests/unit/<package>/mirrors a package offichero_server;tests/unit/scripts/testsscripts/;tests/unit/cli/andtests/unit/mcp/test the sibling products until their owntests/dirs join the gate;tests/integration/,tests/contracts/,tests/perf/are the other legs. Built: 44 of 55 unit dirs match a package. Not built:jobs/(119 files, testsexecution/),kg/(27, testsknowledge/andapi/routes/kg/),transport/(29, testssecurity/andapi/),export/(12, tests a module with no package),check/,harness/,seams/,activity/,packaging/match nothing (#2566). Test (to write):check_engine_package_layoutcompares the two dir sets. Test: fichero-server/tests/unit/scripts/test_check_file_placement.py (check_file_placementwhole-tree mode, baselined in KNOWN_VIOLATIONS;--sincejudges each new file).code-org.folders.scripts-vs-package[OK] —scripts/holds repo-wide gates and tooling (check_*.py,verify_*.sh, release and site scripts); code the engine runs lives in the package, code the builder runs infichero-builder/fichero_builder/; a guard imports only the stdlib and its two helpers (_scan_files.py,_check_floor.py). Test:fichero-builder/tests/test_no_engine_import.py.
B. Naming
code-org.naming.swift-file-is-type[OK] — A Swift file is named for the one primary type it declares;Type+Topic.swiftholds an extension ofTypeand declares no second public type;#Previewandprivatehelper types may share the file. A file holding a family of wire types for one service is named<Service>Types.swiftand is the one allowed bundle (ruled by the owner 2026-11-14: kept). Today 135 files match none of their types and 303 declare more than two top-level types. Built: SwiftLintfile_length/type_body_lengthbound the size, not the count. Built (#1944):check_swift_one_type_per_file, baselined per file inKNOWN_VIOLATIONS, the count may only fall; it also judges the View shape word and place and theIOS/MacOSspelling (code-org.naming.swift-views-end-view,code-org.naming.swift-platform-suffix). Test: fichero-server/tests/unit/scripts/test_check_swift_one_type_per_file.py;check_swift_one_type_per_file --self-test.code-org.naming.swift-views-end-view[OK] — AView-conforming type ends inView, or in one of the shape words the shell uses (Pane,Sheet,Row,Bar,Button,Menu,Picker,Popover,Cell,Badge,Label,Overlay,Section,Item,Field,Panel,Strip,Card,Line,Notice,Pill); a type underViews/that is not a view is named for what it is (*Policy,*State,*Model). A View type outsideViews/lives inApp/Menus/(menu commands) or is misplaced. Today 33 View types sit outsideViews/, 30 of them menus (#1944). Built:check_swift_one_type_per_filerule 3, baselined;check_file_placementjudges a new one by the same rule. The guard’sSHAPE_WORDSalso accepts the shapes the tree already uses (Host,Content,Modifier,Stage,Screen,Page,Tab,Tabs,Toolbar,Header,Footer,Chip,Indicator,Banner,Grid,List,Stack,Canvas,Editor,Viewer,Inspector,Reader,Sidebar,Window,Scene,Renderer,Commands), and a*Sceneor*WindowunderApp/(the app’s own window roots) may stay outsideViews/. Test: fichero-server/tests/unit/scripts/test_check_swift_one_type_per_file.py;check_swift_one_type_per_file --self-test.code-org.naming.swift-platform-suffix[OK] — A platform-specific file or type ends inIOSorMacOS(ruled by the owner 2026-11-14); today 13 files useIOS, 2 useiOS, 1 usesMacOS, so the twoiOSfiles are renamed. Built:check_swift_one_type_per_filerule 4 flags a file or type endingiOS,macOSoriOSOnly, baselined (#1944). Test: fichero-server/tests/unit/scripts/test_check_swift_one_type_per_file.py;check_swift_one_type_per_file --self-test.code-org.naming.python-modules[OK] — A Python module issnake_caseand named for what it does (segment_readings.py,kraken_runtime.py), never for its layer alone (utils.py,helpers.py) and never a stdlib name at the package root (core/logging.pyis inside a package and allowed). Every module in the four products passes. Test: fichero-server/tests/unit/scripts/test_check_python_comment_hygiene.py (the scan floor walks every module); the name rule rides withcheck_engine_package_layoutwhen it lands.code-org.naming.python-tests[OK] — A test file istest_<what_it_proves>.py, in the folder mirroring the code it tests; when it pins an issue the number is a suffix,test_<what>_<issue>.py(553 of 2,434 files, the convention in use). A prefix form (test_6085_one_listing.py, one file) is wrong. A behaviour id from a spec goes in the docstring, not the name. Built:test_globsinharness.toml. Not built: the suffix rule (#1915). Test (to write): one rule incheck_engine_package_layout. Test: fichero-server/tests/unit/scripts/test_check_file_placement.py (check_file_placementwhole-tree mode, baselined in KNOWN_VIOLATIONS;--sincejudges each new file).code-org.naming.swift-tests[OK] — A Swift test file ends inTests.swiftand names the type or surface it covers (PageImageGridTests.swift); the 11 non-test helpers (TestFixtures,AppSource,EngineHarness…) carry no suffix. Test:scripts/check_swift_test_self_references.py.
C. Dead code
code-org.dead.no-unused-files-swift[PARTIAL] — No Swift file whose types nobody else references. Built:check_dead_files.py(#1945) with 18 known candidates. Not built:peripheryas the whole-project tool, nightly, so the extension-only false positives (5 of 18) stop living in an allowlist. Test:scripts/check_dead_files.py; (to write)check_periphery_ratchet, nightly, baseline count never rising.code-org.dead.no-unused-python[GAP] — No Python module, function or class with zero references, and no route that no client, CLI command or MCP tool reaches.vultureat confidence 80 over the four packages, baselined and shrink-only, per batch (seconds); jcodemunchfind_dead_codestays the advisory cross-check. Today one module has no reference anywhere (media/image_prep_samples.py) (#1945; issue to file). Test (to write): guardcheck_vulture_ratchetwith--self-testplanting an unused function.code-org.dead.test-only-code[PARTIAL] — Production code reached only by its own test is dead with a pension: delete the code and the test together. The 6 Swift types reached only fromfichero/Tests(CacheModel,DragDropModel,MCPServersSheet,IntegrationsPlaceholderSheet,PageImageGrid,FicheroShortcuts) go with their tests (ruled by the owner 2026-11-14; review batch S5). Test (to write):check_dead_filescounts a reference fromfichero/Testsseparately and reports “test-only” (#1945). Built: S5 deletedCacheModel,MCPServersSheetandIntegrationsPlaceholderSheetwith their tests;DragDropModelandPageImageGridwait for a later batch (diff bound);FicheroShortcutsstays, as the Shortcuts and Siri phrases are a product feature.ScrollWheelZoom,SimpleWorkflowView,WorkflowExecutionViewandWorkflowChainListView(with its parts) are outside ruling 3 and stay, with theirKNOWN_VIOLATIONSwaivers, until the owner rules on them. Guard:scripts/check_dead_files.py; test:fichero-server/tests/unit/scripts/test_check_dead_files.py.code-org.dead.no-commented-out-code[OK] — No commented-out code blocks; aTODO/FIXMEcites an issue. Test: fichero-server/tests/unit/scripts/test_check_comment_hygiene.py, fichero-server/tests/unit/scripts/test_check_python_comment_hygiene.py.code-org.dead.waiver[PARTIAL] — A deliberate keep is aKNOWN_VIOLATIONSentry (or a# noqa: vulture/// periphery:ignorecomment) that names the issue and the reason in one line; an entry whose file is gone fails the guard; the list only shrinks. Built: the pattern incheck_dead_files.pyandcheck_duplicate_paths.py. Not built: no guard refuses an entry with no#NNNN(#1945). Test (to write):_check_floor.require_reasoned_allowlistshared by the guards.
D. Size
code-org.size.swift-file[OK] — A Swift file is under 400 lines (warning) and never over 1000 (SwiftLint error, the gate); shell files (ContentView*,Sidebar*) never over 1000 with no allowlist (#3040). A type body is under 250 lines (warning), 500 (error); a function under 50, 100. Today one file is over 1000 (SpaceSceneView.swift, 1169, under an inlineswiftlint:disable file_length) and 86 are between 400 and 1000. Test: fichero-builder/tests/test_lint.py (the per-file size ratchet),scripts/check_shell_chrome.pyrule 3.code-org.size.swift-split[OK] — A split is by concern intoType+Topic.swiftextensions or into sub-views in their own files, in the same folder; neverHelpers.swift. A new file underfichero/ficherocompiles by being on disk (synchronized root,AGENTS.mdrule 10); a move isgit mv;scripts/add-swift-file.rbandscripts/remove-swift-file.rbare for the test targets and for amembershipExceptionsentry, never a hand edit ofproject.pbxproj. Test: fichero-server/tests/unit/scripts/test_check_xcode_registration.py.code-org.size.python-file[GAP] — A Python module is under 1,500 lines (ruled by the owner 2026-11-14: 1,500, as a ratchet); a generated module (*_generated.py) is exempt; the gate is a ratchet (no module grows past its own count, the count of modules over the line never rises). Today 84 non-generated modules are over 1,000 and 8 over 3,000 (db/__init__.py8,503;workflows/tools/vision_base.py6,430;api/routes/document/segments.py6,150;execution/jobs.py5,554;llm/__init__.py5,119). A package__init__.pyre-exports and holds no logic beyond 200 lines. Test (to write):check_python_file_size_ratchet, baseline json beside the swiftlint one (#2566).code-org.size.python-split[GAP] — A split moves whole functions and classes into a sibling module named for the concern (segments.py→segments/package withreadings.py,conversion.py…), every importer repointed in the same commit, no re-export left behind unless the package__init__is the public door. Test: the ready check’sred_on_baseandscripts/check_openapi_route_set_current.pyprove nothing moved off the contract (#2566).
E. Ratchets and when they run
code-org.enforce.per-batch-placement[OK] — Every batch is checked for where it put its files, not only the nightly tree: a guard besidecheck_folder_organization.py,check_file_placement --since <base>, readsgit diff --name-status <base>..HEADand judges each ADDED or RENAMED path (the new name) against the rules of this spec: a Swift file underfichero/fichero/<Layer>/<Feature>/whose layer and feature exist and whose name followscode-org.naming.swift-*, with its test under the mirror folder offichero/Testswhen the batch adds a test; a Python module inside a package offichero_server(never the package root),snake_case, its test undertests/unit/<package>/namedtest_<what>[_<issue>].py; nothing new at the repo root or atapi/routes/root; no new module that aliasessys.modules. A misplaced file is red with the path it should have, one line per file (the file, an arrow, the folder it belongs in, and the rule in a few words). Wired throughharness.tomlsince_guardsonfichero/andfichero-server/(the--sinceshape of #6318), so it runs in the guards rung of every batch under the 60 s budget; the whole-tree question stays withcheck_folder_organization.py. A deleted or modified-in-place file is not judged (the tree’s debt is the nightly guard’s). Not built (#1944; issue to file). Test (to write):check_file_placementwith a--self-testthat stages a synthetic range holding one right and one wrong file per rule; a pytest underfichero-server/tests/unit/scripts/that runs it over a temp repo. Built (#6607): the Python and repo-root rules, wired on every diff (since_guardsprefix “”); a new test also passes in atests/unit/folder the merge-base already had. The Swift rules are built too: a new.swiftunderfichero/fichero/sits in a layer folder, a new View type underViews/<Feature>/orApp/Menus/, the name passes the file-is-type, shape-word andIOS/MacOSrules, and a new test underfichero/Tests/Unit/is*Tests.swiftin the mirror of an existing app folder. Test: fichero-server/tests/unit/scripts/test_check_file_placement.py;check_file_placement --self-test.code-org.ratchet.per-batch[OK] — Everyscripts/check_*.pynot inharness.tomlguard_skipruns on each batch in the builder’s guards rung, under 60 s each, from the pinned copy; the ready check runslint.pyper touched file;since_guardsrunscheck_swiftlint_warning_ratchet.py --since <base>when the diff touchesfichero/. Test:fichero-builder/tests/test_build_check.py.code-org.ratchet.nightly[OK] — The whole-tree and build-needing guards run in the nightly gate (guard_skip, reasons inpipeline/projects/fichero.toml[ladder.skip]):check_swiftlint_warning_ratchetover the whole app,check_coverage_ratchet,check_release_size_ratchet,check_hang_ratchet,check_test_plans_runnable. Test: fichero-builder/tests/test_verify_all.py.code-org.ratchet.swift-compiler-warnings[GAP] — The build rung’sxcodebuildlog from a CLEAN build (incremental builds report only the files they recompiled) is counted forwarning:lines, deduplicated by file, line and text, in two buckets: hand-written (fichero/fichero,fichero/Tests, the client package’s ownSources/) and generated (the swift-openapi-generator plugin output underBuildToolPluginIntermediates,*.generated.swift), each against a committed baseline (swift_compiler_warning_baseline.jsonbeside the swiftlint one inscripts/, ruled by the owner 2026-11-14) that never rises; a lower count prints the number to lower it to,--update-baselineis a decision in its own commit. Per batch because the build already runs; nightly on the Release configuration too. Checked 2026-11-14: nothing counts warnings today (check_tool.pybuildkeepserror:lines) (#4446; issue to file). Test (to write): guardcheck_swift_compiler_warning_ratchet --log <path>with a--self-testover a synthetic log holding both buckets, wired as a build-rung post-step.code-org.ratchet.generated-warnings-fixed-at-source[GAP] — A warning in generated code is never fixed by editing the generated file (AGENTS.mdrule 3). It is fixed where it comes from, in this order: the generator config (fichero/fichero-api-client/Sources/FicheroAPIClient/openapi-generator-config.yaml), the generator or runtime package version (Package.swiftrange andPackage.resolvedpin), the target’s Swift settings (upcoming features, import access levels), the OpenAPI schema the engine emits. Last resort: a baseline entry in the generated bucket naming the upstream issue and the reason, dropped when upstream ships. Worked example (owner’s build, 2026-11-14): 3× “public import of ‘Foundation’ was not used in public declarations” and 1× the same forOpenAPIRuntimein the generatedTypes.swift. Cause: swift-openapi-generator 1.13.0 (its PR #883) putspublic importofOpenAPIRuntimeand ofFoundation.URL/.Data/.Dateat the head of every generated file, and since 1.13 the output is split into nine files, soTypes.swift(theAPIProtocolonly) uses none of them in a public declaration; upstream issue #968, a duplicate of #946, fix pending in PR #947 (Swift 6.4 warning suppression). Not fixable from the config (accessModifier: publicis what the app needs), not from a target setting (SE-0443 has no per-group suppression), not from the schema (the schemas file usesDate412 times; the warning is per file). The fix that applies is the package version: the repo pins 1.10.3 (Package.resolved), which is warning-free, butPackage.swiftsaysfrom: "1.6.0", so the owner’s Xcode resolved 1.13.1 and built the warnings the builder never sees. Cap the range at"1.6.0"..<"1.13.0"until #947 ships, so every machine resolves the same generator (#4446; issue to file). Test (to write):check_swift_compiler_warning_ratchetrefuses a generated-bucket baseline entry with no upstream reference; aPackage.swiftrange test infichero/fichero-api-client/Tests/.code-org.ratchet.python-type-warnings[GAP] —pyrightin basic mode over the four packages, errors and warnings counted against a committed baseline (pyright_baseline.jsoninscripts/), never rising; nightly first (minutes over 373 modules), per batch with--sinceon touched files once the whole-tree count is stable. ruff needs no ratchet: its set is error-only and at zero. Checked 2026-11-14: no pyright or mypy in the repo (#4446; issue to file). Test (to write): guardcheck_pyright_ratchetwith--self-test.
F. Enforcement map
| Rule | Guard today | Status |
|---|---|---|
| placement of every added or renamed file, per batch | check_file_placement --since (Python and root) |
[PARTIAL] the Swift rules are not built |
| root allowlist | — | [GAP] check_repo_root |
| Swift feature folders, 18-file cap | check_folder_organization.py |
[OK] with 8 known offenders |
| Models/Services by feature | check_folder_organization.py allowlist |
[GAP] until the two entries leave |
| Swift test mirror | — | [GAP] in check_folder_organization |
| Python package root, test mirror, shims, test names | — | [GAP] check_engine_package_layout |
| one type per file, View suffix, platform suffix | — | [GAP] check_swift_one_type_per_file |
| dead Swift files | check_dead_files.py |
[OK]; periphery nightly [GAP] |
| dead Python | — | [GAP] check_vulture_ratchet |
| commented-out code | check_comment_hygiene.py, check_python_comment_hygiene.py |
[OK] |
| Swift sizes | SwiftLint, check_shell_chrome.py, lint.py |
[OK] |
| Python sizes | — | [GAP] check_python_file_size_ratchet |
| SwiftLint warnings | check_swiftlint_warning_ratchet.py |
[OK] per batch --since, nightly whole tree |
| Swift compiler warnings, two buckets | — | [GAP] check_swift_compiler_warning_ratchet |
| generated warnings fixed at source | — | [GAP] same guard + the generator range cap |
| Python type warnings | — | [GAP] check_pyright_ratchet |
Build order
Stage 1 — guards first, then the tree
Step 1.0 — placement checked on every batch
- Behaviours:
code-org.enforce.per-batch-placement - Tests:
check_file_placement --self-test; fichero-server/tests/unit/scripts/test_check_file_placement.py; harness.tomlsince_guardsgains the guard, proved by fichero-builder/tests/test_guard_inputs.py - Size: M
Step 1.1 — the engine layout and root guards
- Behaviours:
code-org.folders.root - Tests: (to write)
check_engine_package_layout,check_repo_root, each with--self-test; baselined on today’s tree - Depends on: 1.0
- Size: M
Step 1.2 — the Swift file guard
- Behaviours:
code-org.naming.swift-file-is-type,code-org.folders.swift-view-local-state,code-org.folders.swift-test-mirror - Tests: (to write)
check_swift_one_type_per_file; new rules in scripts/check_folder_organization.py - Depends on: 1.1
- Size: M
Step 1.3 — the ratchets
- Behaviours:
code-org.ratchet.swift-compiler-warnings,code-org.ratchet.python-type-warnings,code-org.size.python-file,code-org.dead.no-unused-python,code-org.dead.no-unused-files-swift - Tests: (to write)
check_swift_compiler_warning_ratchet,check_pyright_ratchet,check_python_file_size_ratchet,check_vulture_ratchet,check_periphery_ratchet; fichero-builder/tests/test_build_check.py for the build-rung post-step - Depends on: 1.1
- Size: M
Step 1.4 — the generator range cap
- Behaviours:
code-org.ratchet.generated-warnings-fixed-at-source - Tests: fichero/fichero-api-client/Tests/FicheroAPIClientTests/GeneratorRangeCapTests.swift; (to write) the generated bucket of
check_swift_compiler_warning_ratchetat zero on a clean build - Depends on: 1.3
- Size: S
Step 1.5 — dead code out
- Behaviours:
code-org.dead.test-only-code,code-org.dead.waiver - Tests: scripts/check_dead_files.py (the test-only report), (to write)
_check_floor.require_reasoned_allowlist - Depends on: 1.3
- Size: S
Stage 2 — the tree (one review batch per step; the review names the files)
Step 2.1 — shims out of api/routes
- Behaviours:
code-org.folders.python-no-shim-modules - Tests: scripts/check_openapi_route_set_current.py, fichero-server/tests/unit/api/test_routes_kg_reset_removed.py
- Depends on: 1.1
- Size: S
Step 2.2 — loose engine modules into packages
- Behaviours:
code-org.folders.python-packages - Tests: (to write)
check_engine_package_layoutwith an empty root allowlist beyond the two files - Depends on: 2.1
- Size: M
Step 2.3 — Python test folders renamed to their packages
- Behaviours:
code-org.folders.python-test-mirror,code-org.naming.python-tests - Tests: (to write)
check_engine_package_layoutmirror rule at zero - Depends on: 2.2
- Size: M
Step 2.4 — Models/ and Services/ by feature
- Behaviours:
code-org.folders.swift-models-services-by-feature - Tests: scripts/check_folder_organization.py with
ModelsandServicesout ofKNOWN_VIOLATIONS - Depends on: 1.2
- Size: M (review lanes S1–S4, one feature cluster each)
Step 2.5 — Views/Components and Views/Library emptied of feature files
- Behaviours:
code-org.folders.swift-feature-folders - Tests: scripts/check_folder_organization.py with
Views/Components,Views/Libraryout ofKNOWN_VIOLATIONS - Depends on: 1.2
- Size: M
Step 2.6 — names
- Behaviours:
code-org.naming.swift-views-end-view,code-org.naming.swift-platform-suffix - Tests:
check_swift_one_type_per_file(built in 1.2); its baseline lowered to the files not renamed - Depends on: 1.2
- Size: S
Step 2.7 — the oversized engine modules split
- Behaviours:
code-org.size.python-split - Tests: scripts/check_openapi_route_set_current.py, (to write)
check_python_file_size_ratchetbaseline lowered per module - Depends on: 1.3, 2.2
- Size: M (review lanes P4, one module each)
Test matrix
| Leg | This surface? | Pins | File |
|---|---|---|---|
| Pure rule (Swift) | n | — | — |
| Backend (pytest) | y | every guard’s --self-test and the builder’s build-rung post-step |
fichero-server/tests/unit/scripts/, fichero-builder/tests/ |
| MCP / CLI / UI legs | n | contributor tooling, no user surface | — |
Rulings (owner, 2026-11-14)
- View-only
@Observablestate sits beside its view inViews/<Feature>/;Models/holds shared state (code-org.folders.swift-view-local-state). - The
<Service>Types.swiftwire bundles stay as the one exception to one type per file (code-org.naming.swift-file-is-type). - The six test-only types are deleted together with their tests, in batch S5 (
code-org.dead.test-only-code). - Platform suffixes are
IOSandMacOS(code-org.naming.swift-platform-suffix). - The Python size line is 1,500 lines, as a ratchet (
code-org.size.python-file). - The compiler-warnings baseline lives in
scripts/beside the swiftlint one (code-org.ratchet.swift-compiler-warnings).