Non-contract Context/Notes updates from the user's long-term framing:
- G-004: the two further motivations (third-party distribution platforms
that disallow binaries; the consent promise as an auditable product
commitment); binaries must still OPERATE in the tree post-achievement
(local uncommitted experimentation + permissive derived projects - scan
polices the committed tree only, ignore rules double as drop-in
enablement); exit-path assessment for the src/vfs interim exception
(prefer suite batteries + per-package punkbin library artifacts; whole
.vfs zip archives recorded as an open third-class option).
- G-006: the consent gate recorded as a product commitment, not just
anti-surprise hygiene.
- G-067: buildsuites as a producing source - per-platform library .tm
artifacts as punkbin's second artifact class (platform canon + G-103
metadata pattern); retrieval-target/G-004 ignore interplay.
- G-114: provenance boundary - binary .tm arrive via G-067/local drops,
never checked into punkshell; drop-in acceptance ties to G-004's
operate-in-tree requirement.
Goal/Acceptance contract lines untouched throughout.
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
@ -9,6 +9,16 @@ Acceptance: a scan of the committed tree finds no executable binaries (shared li
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.
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.
Two further motivations recorded 2026-07-22 (user framing):
- **Third-party distribution eligibility**: a binary-free punkshell is a candidate
for distribution platforms that disallow checked-in binaries.
- **The consent promise as a product commitment**: punkshell guards the promise
that binaries reach the user's machine over the network ONLY by explicit user
action/consent unless configured otherwise (the G-006 gate and its G-067
sibling are the enforcement points). A binary-free repo makes the promise
auditable: everything binary is retrieved, and every retrieval is consented.
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.
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:
This goal is the integrating outcome of two enabling goals:
@ -40,6 +50,37 @@ A standing repo-wide rule in root `AGENTS.md` (User Preferences) already directs
## Notes
## Notes
- 2026-07-22 (user framing): achieving this goal must NOT stop binaries
OPERATING in the tree - the no-checkin policy is about the COMMITTED tree
only. Two working modes stay first-class forever: (a) quick local
experimentation with uncommitted binaries dropped into the working tree;
(b) derived projects (dev project.new) with a PERMISSIVE binary policy -
generated projects may commit binaries under their own rules. Consequences
for the Approach: the step-4 scan targets the committed tree (never a
working-tree police); ignore rules added at removal time double as the
drop-in enablement (local binaries stay conveniently uncommitted); and
- 2026-07-22 (user framing + assessment): EXIT PATHS for the src/vfs/*.vfs
interim exception - the .vfs binary payloads leave the committed tree via
some mix of: (i) suite-built runtime batteries (G-103 attached images
already shrink kit .vfs payloads toward pure punkshell script payload);
(ii) per-package punkbin LIBRARY artifacts (G-067 channel - buildsuite-built
.tm/pkg libraries as a second punkbin artifact class) declared into kit
assembly; (iii) possibly whole zipped binary-carrying .vfs archives as a
THIRD punkbin artifact class. Assessment 2026-07-22 (agent, user question):
prefer (i)+(ii) as the primary paths - per-package artifacts dedupe across
kits, keep provenance/versioning granular, reuse the platform canon and the
G-103 metadata pattern, and share one consent story; whole-.vfs archives
couple unrelated components and churn on any payload change, so (iii) is
recorded as an OPEN option for release-snapshot/derived-project convenience
rather than the primary mechanism - decide when removal actually forces the
payloads out. A declarative .vfs composition surface (toml-defined payload
pulling from (i)/(ii), preserving drop-in simplicity) is the candidate
glue - see the G-115 proposal (2026-07-22) if adopted.
- Depends on G-005 and G-006. Sequence G-005 ∥ G-006, then G-004.
- 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 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.
- 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.
1. **Default:** a separate, related binary-artifacts repository (sibling to this source repo, not part of it) holding pre-built artifacts for supported platforms.
1. **Default:** a separate, related binary-artifacts repository (sibling to this source repo, not part of it) holding pre-built artifacts for supported platforms.
2. **User-configured:** a user-supplied source URL (internal mirror, local file server, etc.) that overrides the default.
2. **User-configured:** a user-supplied source URL (internal mirror, local file server, etc.) that overrides the default.
The critical behavioural requirement is **consent gating by default**: the download must not happen silently. A first-time build that silently reaches out to a remote source would be surprising and a network-exfiltration concern. The user must explicitly opt in — via a config flag set before the build, or an interactive prompt at build time — before any download occurs. Once consent is given (e.g. a config flag persisted), subsequent builds for the same artifact set don't re-prompt.
The critical behavioural requirement is **consent gating by default**: the download must not happen silently. A first-time build that silently reaches out to a remote source would be surprising and a network-exfiltration concern. (2026-07-22 user framing: this gate is a PRODUCT COMMITMENT, not just anti-surprise hygiene - punkshell promises that binaries are only retrieved from the network by explicit user action/consent unless configured otherwise. This goal and its G-067 sibling are the enforcement points; a binary-free repo per G-004 is what makes the promise auditable.) The user must explicitly opt in — via a config flag set before the build, or an interactive prompt at build time — before any download occurs. Once consent is given (e.g. a config flag persisted), subsequent builds for the same artifact set don't re-prompt.
This goal is parallel to and independent of G-005. A user with zig uses G-005; a user without zig (or choosing not to build) uses G-006. Either path satisfies G-004's retrieval requirement.
This goal is parallel to and independent of G-005. A user with zig uses G-005; a user without zig (or choosing not to build) uses G-006. Either path satisfies G-004's retrieval requirement.
