punkshell/goals/G-112-maketcl-subcommand-rename.md

G-112 make.tcl subcommand rename: stage-true vocabulary around the promotion gates

Status: proposed Scope: src/make.tcl (subcommand tables, dispatch gating, help/workflow text); src/project_layouts/vendor/punk/basic/src/make.tcl + src/project_layouts/vendor/punk/project-0.1/src/make.tcl + src/modules/punk/mix/#modpod-templates-999999.0a1.0/templates/project_layouts/vendor/punk/project-0.1/src/make.tcl (layout copies via established sync channels); AGENTS.md + src/AGENTS.md + src/modules/AGENTS.md + src/lib/AGENTS.md + src/vfs/AGENTS.md + src/tests/AGENTS.md + src/tests/shell/AGENTS.md + README.md + src/README.md (workflow references); src/tests/shell/testsuites/punkexe/scriptexec.test + src/tests/shell/testsuites/punkexe/staticruntime.test (as touched) Goal: make.tcl's subcommand vocabulary names pipeline stages truthfully: vfs becomes bake (kit assembly only), project is retired in favour of bakehouse - a consumer umbrella that chains packages+bake and refuses to run on dirty src - and no command silently spans the promotion gates (bootsupport, vfscommonupdate). packages, modules, libs, bootsupport, vfscommonupdate, bin keep their names. Acceptance: (1) make.tcl bake on a clean checkout produces kits byte-comparable to what make.tcl vfs produced at the same tree (allowing only known-nondeterministic zip metadata), and additionally runs the vfslibs phase so a bake cannot ship stale binary libs; (2) make.tcl project and make.tcl vfs still work as deprecated aliases that print a one-line deprecation notice naming their replacement; (3) make.tcl bakehouse defaults -dirty-abort on and its abort message names the granular developer flow; (4) make.tcl help/workflow output and every doc in Scope describe the two-persona flow (consumer: bakehouse; developer: packages -> test -> bootsupport/vfscommonupdate -> commit -> bake) with no remaining instruction to run bare make.tcl project as the recommended path; (5) the punkexe testsuites pass against a kit built with the new names.

Context

The current names describe inputs (vfs, modules) or vague scope (project) rather than pipeline stages, and project silently spans the promotion gate: it rebuilds modules/libs AND bakes kits while deliberately excluding vfscommonupdate in between. That exclusion is correct design (payload promotion is a confirm-gated, committed act) but the naming hides it, so developers mid-change run project expecting their built modules to reach the kits.

The clarifying model (session 2026-07-21): one build stage, two promotion gates, one bake.

• packages (= modules + libs): src -> /modules|lib (dev world)
• bootsupport: promote built modules into make.tcl's own boot environment (src/bootsupport)
• vfscommonupdate: promote built modules into the kit payload (src/vfs/_vfscommon.vfs), confirm-gated, committed for provenance
• bake (currently vfs): assemble kits/zipkits/exes from promoted payload + custom vfs folders + runtimes, install to bin/

The two personas resolve the "why would anyone want project's combo" question:

• Consumer (clean checkout, wants baked goods): the gates are already satisfied by the committed tree - packages+bake with no commit step is CORRECT for them. This was project's legitimate audience.
• Developer (changing payload): must pass the gates explicitly; the commit is the publishing act, not a build step.

bakehouse defaulting -dirty-abort on makes this structural rather than documentation: clean checkout -> single uninterrupted command; dirty src -> refusal pointing at the granular flow. The existing PROVENANCE-WARNING machinery is the hinge (today's warn-only default is what lets the personas blur). The name extends the metaphor usefully: the bakehouse bakes from the committed recipe; uncommitted scribbles must be published first.

Name selection record: bakehouse chosen 2026-07-21. Rejected: project (wrong connotation - sounds like everything including promotion), build (conceptual collision with zig binary building in buildsuites), kits (too close to kit runtimes), all (implies promotion included). bake for the kit-assembly step: distinct from vfscommonupdate where vfs read as an abbreviation of it, and names the output-producing act rather than an input folder.

Approach

• Rename vfs -> bake; fold the vfslibs phase into bake (today gated {project vfslibs} only, so a bare vfs run can ship stale binary libs in custom vfs folders - trap closed by this goal). Decide whether vfslibs survives as a standalone narrowing.
• Retire project; add bakehouse = packages + bake, -dirty-abort default ON.
• Keep project/vfs as thin deprecated aliases (one-line mapping before dispatch + deprecation notice) for a transition window.
• Update SUBOPTS/SUMMARIES/HELPTEXTS/known_commands tables, end-of-run guidance strings (make.tcl:3503-3512, ~4956), workflow subcommand output (teach the two-persona flow), then sweep docs and layout-template make.tcl copies in Scope.
• Layout copies re-vendor through the normal template sync; kit payload/bootsupport copies of punk::mix::cli follow the normal packages -> bootsupport/vfscommonupdate flow.

Open decisions

• vfslibs final disposition: fold into bake only, vs also/instead treat binary libs as promoted payload under vfscommonupdate (provenance argument).
• Deprecation window length for the project/vfs aliases.

Notes

• CI-check candidate (independent value, could be split out): vfscommonupdate on a clean checkout must produce zero diff - nonzero means forgotten promotion or a build-reproducibility bug.
• Artifact provenance carrier: kits reference the committed tree (punkorigin.toml / kit metadata direction, G-027 interim carrier) - VCS stays the payload ledger.
• 2026-07-21 (user-approved pairing): G-104 (make.tcl buildsuite surface) edits the same make.tcl subcommand surface - SUBOPTS/SUMMARIES/HELPTEXTS tables, help/workflow output. Ordering: this goal lands first, or the two run together as one make.tcl-surface window, so G-104's buildsuite group and the workflow text are written once in the stage-true vocabulary. G-104's sibling-ergonomics note still reads make.tcl 'vfs' - that text joins this goal's rename sweep when both land. Mirror note in G-104.
• G-035 relationship (recorded 2026-07-24 after overlap review): its mixed-provision guidance lands in the same src/modules/AGENTS.md + src/lib/AGENTS.md this goal's rename sweep updates - coordinate the edit windows.
• G-047 relationship: its punkproject.toml schema addition and ignore-rule seeding ride the same layout sync channels this goal's renamed make.tcl copies travel.