# G-004 No executable binaries committed to the repository

Status: proposed
Scope: repo-wide (bin/, src/vfs/, src/vendorlib/, src/vendormodules/, src/bootsupport/)
Goal: the committed repository contains no executable binaries; zip-based .tm modules are allowed but not if they embed executables.
Acceptance: a scan of the committed tree finds no executable binaries (shared libs, .exe, native .so/.dll/.dylib, bare ELF/Mach-O); any zip-based .tm modules present contain no embedded executables; the binary artifacts previously committed are retrievable via G-005 (build from source) or G-006 (pre-built download) so their removal does not break builds.

## Context

The ultimate aim is that the committed repository contains no executable binaries. This is a hygiene and reproducibility goal: binaries in version control are opaque to review, bloat the repo, and make the build non-reproducible from source. Today the repo violates this — binary libraries are committed in the VFS folders (`src/vfs/`), `src/vendorlib/`, `src/vendormodules/`, and `src/bootsupport/`. These are present because there is currently no automated way to rebuild or retrieve them; removing them before an alternative exists would break builds on a clean checkout.

Zip-based `.tm` modules are a permitted exception to the "no binaries" rule because they are module archives, not executables — but a zip-based `.tm` that embeds an executable (e.g. a native shared library packaged inside the module) is not permitted. The distinction is content, not file extension.

This goal is the integrating outcome of two enabling goals:
- **G-005** provides the build-from-source path (zig build of Tcl9 and other dependencies).
- **G-006** provides the pre-built download path with consent gating.

Both must be in place before the committed binaries can be removed without breaking builds, so G-004 sequences after both.

A standing repo-wide rule in root `AGENTS.md` (User Preferences) already directs agents not to commit new executable binaries, while explicitly not hassling the developer about existing vendor/vfs binaries committed pending this goal's achievement.

## Approach

1. **Inventory.** Identify every executable binary currently committed across `bin/`, `src/vfs/`, `src/vendorlib/`, `src/vendormodules/`, and `src/bootsupport/`. Classify each by what it is (Tcl9 shared lib, twapi, other native extension) and which goal path (G-005 build / G-006 download) will replace it.

2. **Verify alternatives work.** Before removing any binary, confirm the corresponding G-005 build or G-006 download produces an artifact that satisfies the build. Removal without a working replacement breaks clean-checkout builds — the acceptance explicitly requires the alternative retrieval to work.

3. **Remove.** Delete the committed binaries from the tree. Update `.gitignore` / `.fossil-settings/ignore-glob` if needed to prevent re-addition.

4. **Add a scan to verification.** Add a scan step (script or make.tcl target) that checks the committed tree for executable binaries and fails if any are found, so regressions are caught. The scan must recognise the zip-based `.tm` exception: a `.tm` that is a zip is allowed; a `.tm` (or any zip) containing an embedded executable is not.

5. **DOX update.** Once achieved, the AGENTS.md "no binaries" user-preference note can be simplified from "agents must not; existing violations pending" to "agents must not; scan enforced" — but the rule itself stays.

## Alternatives considered

- **Delete binaries now, document manual fetch.** Rejected: no automated retrieval, so every contributor hand-fetches. The intended system (G-005/G-006) exists precisely to avoid this.
- **Allow committed binaries permanently.** Rejected: this is the explicit ultimate aim the user stated. Not a real alternative.
- **Permit zip-based .tm with embedded executables.** Rejected: the user's wording is explicit — "those zip-based .tm modules that contain executables should also not be directly checked in." The content matters, not the extension.
- **Fold G-005 and G-006 into this goal.** Rejected: the build system and download system are each large bodies of work with their own acceptance, and they're independently useful before all binaries are removed. Bundling would make G-004 uncheckable until two large systems are built, and would grow past a one-line-safe summary.

## Notes

- Depends on G-005 and G-006. Sequence G-005 ∥ G-006, then G-004.
- The scan in step 4 should distinguish "executable binary" from "zip archive" and from "zip archive containing an executable." A naive extension-based check is insufficient; content inspection (file magic, zip listing) is required.
- The AGENTS.md user-preference rule is the transition guard: it stops agents from adding new binaries during the G-005/G-006 development period while the developer's existing vendor/vfs binary commits are known and intentional.
- No persisted prior chat on this topic was found in project sessions; the motivation is the user's stated ultimate aim.