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

Status: achieved 2026-07-25
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 -> <projectroot>/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

RESOLVED at activation 2026-07-25 (user-directed dispositions):

- `vfslibs` disposition: folds into bake (binary libs are build outputs, per the
  G-004 direction and archived G-103, achieved 2026-07-22 - see
  goals/archive/G-103-runtime-kit-family.md) - the provenance-argument alternative (promote under
  `vfscommonupdate`) is not taken. Whether `vfslibs` survives as a standalone
  narrowing command is decided in-session during the rename work and recorded
  in Progress.
- Deprecation window for the `project`/`vfs` aliases: keep until the 8.6 arc
  (G-099/G-100/G-101 era) completes - revisit removal when that arc closes.

## Progress

- 2026-07-25 rename core landed (punkshell 0.23.0): vfs -> bake with the
  vfslibs phase folded in (dispatch gate now {bakehouse bake vfslibs}), project
  retired -> bakehouse (packages + bake; -dirty-abort boolean default ON via a
  dedicated OPT_DIRTYABORT_ON fragment; refusal message names the granular
  developer flow), project/vfs kept as deprecated aliases (one-line stderr
  notice + command-word mapping before dispatch; alias definitions mirror their
  targets' options so flags parse identically; degraded fallback mode forces
  bakehouse's dirty default ON since its flag-only -dirty-abort cannot express
  0). SUBOPTS/SUMMARIES/HELPTEXTS/SUBGROUPS/known_commands updated; groups
  renamed to teach the model (build & bake / promotion gates / source
  maintenance / deprecated aliases); end-of-run guidance, plain punkboot_gethelp
  and ::punkboot::workflow_text rewritten to the two-persona flow.
  Verified: tabled + PUNKBOOT_PLAIN help render the new vocabulary; bakehouse
  and the project alias refuse a dirty tree with the granular-flow message;
  help bake/vfs render (alias helptexts marked DEPRECATED).
- IN-SESSION DECISION (per the activation disposition): `vfslibs` SURVIVES as a
  standalone narrowing - it serves quick iteration on the
  src/runtime/vendorlib_vfs.toml declarations without a full bake, matching the
  modules/libs narrowings of packages; its helptext names it a phase of bake.
- Acceptance verification 2026-07-25 (achieved flip):
  (1) bake-vs-vfs byte comparison: on the git-clean tree, FRESH rebuilds of
  punk91 (zip-wrap, tclsfe) and punk86 (kit-wrap, tclkit) via 'make.tcl bake'
  are BYTE-IDENTICAL to the pre-rename 'make.tcl vfs' products snapshotted from
  src/_build (no zip-metadata tolerance needed; a first vacuous pass from
  punkcheck skip-detection was caught and redone with forced rebuilds); the
  vfslibs phase demonstrably runs inside bake (VFSLIBS install lines).
  (2) aliases: 'make.tcl project'/'make.tcl vfs' print one-line deprecation
  notices naming their replacements and run them (dirty-tree refusal reached
  through the project alias).
  (3) bakehouse -dirty-abort defaults ON; the abort names the granular
  developer flow (verified live on a dirty tree).
  (4) help (tabled + PUNKBOOT_PLAIN), workflow (two-persona model), and every
  Scope doc swept (root README, src/README, src/AGENTS.md, src/modules +
  src/lib + src/vfs + src/tests + src/tests/shell AGENTS.md, scriptexec.test +
  tclshcmd.test rebuild comments; src/runtime/AGENTS.md as adjacent hygiene);
  no remaining bare-'make.tcl project' recommendation outside historical
  CHANGELOG entries and proposed-goal contract texts (G-005/G-006/G-057
  Acceptance lines - proposal-first, flagged to the user; the alias keeps them
  executable). Layout make.tcl copies synced via the normal thin-layout
  channels (all three carry the new vocabulary).
  (5) punkexe suites pass against kits built via the new names (54 total,
  0 failed; includes the G-118 piperepl pins after re-materializing the
  tclsh9.0.5-punk working runtime to r2 - a pre-existing stale local
  materialization the window's bake exposed, not a rename regression).
  punkshell 0.23.0.

## Notes

- Activation freshness 2026-07-25: goals_xref.tcl score G-112 re-run at the
  proposed->active flip - top pairs are the already-recorded window partners
  (G-113, G-104) and linked G-047/G-035; remaining unlinked hits (G-090, G-031,
  G-086) are shared-file/term noise with no substantive rename relationship.
  Activated together with G-104 + G-113 as one make.tcl-surface window
  (ordering per the 2026-07-21 pairing note below).
- 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.