19 KiB

Raw Blame History

G-155 stage-true vocabulary part 2: mint stage named, build reserved for compiling, _mint/_bake workdirs

Status: achieved 2026-08-02 Scope: src/make.tcl (SUMMARIES/HELPTEXTS/SUBGROUPS, workflow_text + new TERMINOLOGY block, BUILD-WARNING -> BAKE-WARNING, bakelist vocabulary, workdir paths); src/modules/punk/mix/base-999999.0a1.0.tm + src/modules/punk/mix/cli-999999.0a1.0.tm (workdir paths, antidir/antipattern/reserved lists, legacy vfs-cksums trio disposition); src/vfs/_config/punk_main.tcl + src/vfs/_config/project_main.tcl (dev-mode src/_build path logic); .gitignore + .fossil-settings/ignore-glob (_build glob split per dual-VCS derivation); src/project_layouts (make.tcl copies, gitignore.in + ignore-glob payloads, via established sync channels); src/tests/shell/testsuites/punkexe/ + src/tests/modules/punkboot/ + src/tests/modules/punkcheck/ (pinned tokens: BUILD-WARNING, nobuild, _build paths); AGENTS.md + src/AGENTS.md + src/modules/AGENTS.md + src/vfs/AGENTS.md + src/runtime/AGENTS.md + bin/AGENTS.md + README.md + src/README.md + ARCHITECTURE.md (prose sweep); GOALS.md G-029 entry title (coordinated proposal-first edit) Goal: The pipeline vocabulary is stage-true end to end: 'build' means compiling source to binary and lives only in the arm's-length factories (buildsuite, tool), the src -> projectroot packaging stage is named 'mint' (stamp real versions, pack modpods, prune superseded, install) with packages/modules/libs keeping their G-112 subcommand names, bake-domain prose and tags stop borrowing 'build' (BAKE-WARNING, bake product, rebake), the workdirs teach the same words (src/_bake for kit assembly, per-srcdir _mint for module staging, src/buildsuites/_build unchanged), and ::punkboot::workflow_text carries a TERMINOLOGY block defining the stage verbs so the vocabulary travels into layout copies and generated projects. Acceptance: (1) 'make.tcl help' and 'make.tcl workflow' describe modules/libs/packages with mint vocabulary and no module-stage or bake-domain verb-'build', the persona header reads "one mint stage, two promotion gates, one bake", and the TERMINOLOGY block renders in workflow output; (2) every recap-warning emit site prints BAKE-WARNING (PROVENANCE-WARNING untouched) and BUILD-WARNING survives only in historical records (CHANGELOG, GOALS-archive.md, goals/archive/); (3) on a clean checkout 'make.tcl bakehouse -confirm 0' completes with kit products in src/_bake and module staging under per-srcdir _mint folders, kits byte-comparable to same-tree pre-rename products (allowing only known-nondeterministic zip metadata), src/buildsuites/_build untouched and no new _build content created outside src/buildsuites; (4) bakelist's deployed-state vocabulary agrees with the rename (nobuild -> nobake or a recorded keep-decision) and the punk::mix vfs-cksums trio (store_vfs_build_cksums calls the undefined get_vfs_build_cksums) is repaired or retired; (5) ignore rules updated in both VCS per the derivation rules, layout make.tcl + ignore payloads synced, templates modpod repacked, docs in Scope swept, pinned testsuites updated and passing against kits baked under the new vocabulary, and the project version bumped with a CHANGELOG entry.

Context

Successor to G-112 (achieved 2026-07-25 - see goals/archive/G-112-maketcl-subcommand-rename.md), which renamed the subcommands to stage-true names (vfs -> bake, project -> bakehouse) and whose name-selection record already rejected 'build' for its "conceptual collision with zig binary building in buildsuites". G-112 deliberately left the first stage verb-less: packages/modules/libs kept their names, the help group label stayed "build & bake", and the charter line reads "one build stage, two promotion gates, one bake".

A full-tree terminology survey (2026-08-02 session, user-directed) found the word 'build' carrying four senses plus identifiers:

compile source -> binary (strict): buildsuites/tool/goals arc - dominant, consistent, correct.
module-stage verb: "Build .tm modules ... from src into " (make.tcl SUMMARIES, 4 synced copies) - yet make.tcl:1611-1612 itself admits "The 'building' is generally just assigning a version instead of 999999.0a1 (and some doc string substitution?)". The stage's real work: stamp real versions, pack #modpod-* trees, prune superseded, install under punkcheck.
bake-domain borrowings (the largest conflation set): "the kit still builds and deploys", "rebuilds a single kit", "buildable kits", "build product: src/_build/...", bakelist's nobuild status - and the BUILD-WARNING tag, whose emit sites are ALL in the bake domain (none in the module stage, none in the compile factories; sibling tag PROVENANCE-WARNING already models domain-prefixed naming).
whole-pipeline umbrella: "build system", "consumer build", "build/promotion commands", even "a normal make.tcl bakehouse build" (G-005 detail prose).
identifier families: buildsuite (correct), buildversion.txt, BUILDCOPY, _build dirs, and punk::mix::cli::lib::build_modules_from_source_to_base - which is also the punkcheck -installer identity string (1644 rows in modules/.punkcheck), so its recorded name must not change casually.

The _build directory name is overloaded across three different stages: src/_build (bake work/products), src/modules/_build + src/modules/test/_build (module-stage modpod staging), src/buildsuites/_build (compile area - the only one that deserves the name under strict usage). User direction 2026-08-02: the folder structure should teach the terminology - rename the non-compile workdirs to their stage words.

Name selection record: 'mint' chosen 2026-08-02 (user-directed, from the survey's collision analysis). The stage stamps real versions onto magic-version blanks (999999.0a1.0 + -buildversion.txt) and issues consumable artifacts - minting is the literal act; the register pairs with bake/bakehouse; repo collision check clean (only 'mintty' proper-noun hits in console platform code). Rejected: 'assemble' (taken - bake's own summary verb, assemble_zipcat_image proc), 'stage'/'staging' (taken three ways: _targets// payload staging, layout staging dirs, goal-arc stage numbering - plus VCS staging in a dual-VCS repo), 'install' (taken - punkcheck record type and bin's "Install executables"), 'promote' (taken - the two promotion gates), 'emit' (generic output verb across console/punkbin/buildsuite/test domains), 'package' (circular with the packages subcommand), 'generate'/'produce'/'materialize'/'sync' (established elsewhere), 'mill' (metaphor maps poorly; Mill is a known Scala build tool).

Approach

Ordered sweep (single window, or increments in this order so vocabulary lands before folder mechanics):

make.tcl vocabulary pass: SUMMARIES/HELPTEXTS for packages/modules/libs (mint phrasing), bakehouse ("consumer run: mint + bake from the committed recipe"), bin ("...then bake kits as for bake"), SUBGROUPS label "build & bake" -> "mint & bake", persona header -> "one mint stage, two promotion gates, one bake", workflow_text rewritten (release-sequence rows relabelled mint/promote/promote/bake, "BUILT PACKAGES" -> "MINTED PACKAGES") + the TERMINOLOGY block (drafted below) added; umbrella prose moves to "make run"/"make system" wording.
BAKE-WARNING retag: the print_build_warnings emit + recap strings change; internal proc/var names (print_build_warnings, build_warnings_pending) may follow opportunistically.
Workdir renames: punk::mix::base get_build_workdir mkdir/return src/_bake; cli modpod staging <current_source_dir>/_mint (cli:862); cli:172 running-from-workdir check -> src/_bake; cli:752 legacy src/_build/ construction dispositioned live-or-dead in the work; reserved_words (cli:349), antidir (cli:710), antipatterns (base:347) and make.tcl:6981 exclude lists gain _mint/_bake while keeping _build tolerated; make.tcl:7098 consistency check and bakelist/deploy paths -> src/_bake; punk_main.tcl/project_main.tcl dev-mode simulate-kit logic (src/_build/.vfs -> src/_bake/...).
Ignore rules: .gitignore **/_build/ joined by **/_mint/ and **/_bake/ (keep **/_build/ for buildsuites and stale checkouts); .fossil-settings/ignore-glob derived per .fossil-settings/AGENTS.md.
Docs sweep per Scope (bake-domain and module-stage verb-'build' plus umbrella phrases); archived goals, GOALS-archive.md and CHANGELOG stay untouched as historical record.
Tests: update pinned tokens (inventory in Notes), then run the punkexe/punkboot/punkcheck suites.
Propagation dances: make.tcl modules run syncs the 2 layout make.tcl copies + templates modpod; punk::mix changes need the bootsupport K4 dance (rerun until a pass copies 0 files); root .gitignore propagates to layout gitignore.in payloads via the established G-012 sync (achieved - see goals/archive/G-012-template-payload-safety.md).
Verification bake per Acceptance (3); project version bump (make.tcl output vocabulary is consumer visible - at least patch, likely minor) + CHANGELOG entry.

Transition: the old src/_build, src/modules/_build and src/modules/test/_build become dead after the flip - delete after the first verified bakehouse; ignore/exclude/antidir lists keep tolerating _build so stale checkouts and older layout snapshots stay quiet. punkcheck consequences are limited to recorded paths (a one-time re-install/re-record on first run is acceptable); the -installer identity string build_modules_from_source_to_base is NOT renamed - a mint-named wrapper may be added, the recorded identity stays.

Open decisions

RESOLVED at activation 2026-08-02 (user-directed: recorded leans adopted, G-029 rewording pre-approved):

bakelist deployed-state token: RENAME nobuild -> nobake (bakelist is young (G-121, achieved - see goals/archive/G-121-bakelist-selective-bake.md) and its consumers are in-repo tests). Column-stable output contract preserved under the new token.
get_build_workdir: RENAME to get_bake_workdir in the same pass (API change rides the bootsupport dance; callers verified at activation: make.tcl + punk::mix internals only).
BUILDCOPY punkcheck event + runtime_buildcopyname: KEEP (recorded punkcheck vocabulary); BAKECOPY only with a future punkcheck format change.
G-029 retitle: PRE-APPROVED wording applied at activation ("Mint packaged test:: #modpod modules from src/tests") - title in both tiers; its Goal/Acceptance lines otherwise untouched (contract), body prose rides the sweep.
TERMINOLOGY placement: workflow_text canonical + one-line pointers in README/ARCHITECTURE.
Environment note at activation: only punk901t.exe running (user-confirmed; expected outside the configured bake set - verified against bakelist before the deploy phase).

Progress

2026-08-02 increment A LANDED (payload-frozen): make.tcl vocabulary + TERMINOLOGY block (renders tabled + PUNKBOOT_PLAIN), BAKE-WARNING retag (live recap shows only the three known pre-existing warnings: punkmagic runtime absent + zint i386 x3), bakelist nobake + "bake product:", workdirs src/_bake + /_mint live (verified created and staged), punk::mix base 0.2.0 (get_bake_workdir
- legacy alias; cksums quartet retired) / cli 0.6.0 (mint staging) / punkboot::utils 0.6.2 ("produced" wording) minted and promoted (bootsupport converged, punk::lib 0.6.0 rider), ignore rules split in both VCS (extras|check-ignore empty), docs + test pins swept, layout make.tcl + gitignore.in payloads auto-synced, templates modpod repacked. architecture_lint clean.
2026-08-02 increment A verification bake: fresh src/_bake full bake, 11 kits INSTALLED zero failures (11m29s cold ledger). Byte-compare vs pre-rename snapshot (51 files): 35 byte-identical (incl punk86/punksys/punk905/punkluck86/punkshell902 + all sidecars); 11 missing all accounted (bake_default=false punkdeclare, punkmagic runtime-absent, flat punk91ix86 orphans predating G-127 (achieved - goals/archive/G-127-crosstarget-vfs-bake.md) - tier copy baked correctly, stale experiment stubs); 5 differ (punkbi punk91 punk902z punk9_beta punk9bi_beta) with EVERY member CRC identical - old products predate the punkzip deterministic-assembly switch of G-126 (achieved - goals/archive/G-126-punkzip-accelerator.md) (directory entries + different ratios = older creator), stale baselines masquerading as 'current', not a rename delta. punk905 identical while sharing punk9_beta's vfs clinches it.
2026-08-02 increment B + ACHIEVED flip: punk_main/project_main dev-mode comments follow src/_bake and the modpod scan skips _mint/_bake staging (legacy _build kept); vfscommonupdate promoted the payload (punk::mix 0.2.0/0.6.0, punkboot::utils 0.6.2, punk::lib 0.6.0 + riders punk::args 0.14.0, tclparser 0.1.0, layout 0.3.0, project 0.4.1); full 'bakehouse -confirm 0' green - 11 kits INSTALLED, recap = only the three known pre-existing warnings now tagged BAKE-WARNING, all guidance in mint/bake vocabulary, fresh punk905 payload spot-checked carrying the four updated modules; steady state creates no _build content (mtime proof: src/modules/_build untouched by the bakehouse). Suites: punkexe + punkboot + punkcheck sweep 268 tests / 264 passed / 4 skipped / 0 failed (native tclsh90, -jobs 16; three initially-missed 'bake product:' label regexps fixed in maketclkitlocations + maketclplatform). Live-tier gates: nobuild absent from code/tests; BUILD-WARNING remains only in historical records, dead old-workdir leftovers and this file's dated survey prose. punkproject.toml 0.42.0 + CHANGELOG entry; projectversion check OK.
Manual leftover (deliberate): old src/_build + src/modules/_build + src/modules/test/_build left in place (ignored, inert - src/modules/_build holds a #tarjar staging copy; tarjar disposition is user-manual per standing note). Delete at leisure.

Notes

Drafted TERMINOLOGY block for ::punkboot::workflow_text (plain ASCII, width <= 100):

TERMINOLOGY (stage verbs - one word, one stage)
----------------------------------------------------------------------------
  build    compile source to binaries. Lives in the arm's-length factories:
           'make.tcl buildsuite' (whole Tcl runtimes from external sources,
           src/buildsuites, workdir src/buildsuites/_build) and 'make.tcl
           tool build' (vendored zig tools, src/tools). Nothing in
           mint/promote/bake compiles anything: bakes succeed with no build
           toolchain installed.
  mint     stamp real versions onto magic-version sources (999999.0a1.0 ->
           the <pkg>-buildversion.txt value), pack #modpod-* trees, prune
           superseded copies and install the results into the projectroot
           trees (modules*/ lib*/). The modules/libs/packages subcommands
           are the mint stage; staging area <srcdir>/_mint.
  promote  propagate minted packages into the two gated consumption trees:
           src/bootsupport (make.tcl's own boot environment) and
           src/vfs/_vfscommon.vfs (the committed kit payload) - the
           bootsupport and vfscommonupdate promotion gates.
  bake     assemble kit/zipkit executables from promoted payload + runtimes
           (workdir src/_bake) and deploy them to bin/. Consumer umbrella:
           bakehouse = mint + bake from the committed recipe.
  fetch    bring third-party inputs to the tree: libfetch (punkbin lib
           artifacts), vendorupdate (vendored sources).
  deploy   the final copy of a baked kit from src/_bake to bin/<kit>.
Mechanism words keep their scoped meanings: stamp (version fields at mint,
icons/resources at bake via punkres), install (punkcheck-recorded placement
at any stage), sync (thin-layout copies), materialize (vfslibs payload
declarations, libfetch trees).

Identifier keep-list (out of scope, reasons recorded):

build_modules_from_source_to_base - punkcheck -installer identity, 1644 rows in modules/.punkcheck; renaming orphans change-detection records. Wrapper-only if a mint-named surface is wanted.
-buildversion.txt sidecars + the module-header boilerplate naming them - hundreds of files; re-read as "the version stamped when minted".
BUILDCOPY event + runtime_buildcopyname (recorded punkcheck vocabulary; see Open decisions).
buildsuite/buildsuites names, build.zig/build.zig.zon, tcl::build-info, punkbin build_id - correct strict usage or external schema.
src/build.tcl - kettle's required filename (disclaimer already at src/README.md:55); doc.build - kettle vocabulary, unambiguous under its doc. prefix.
Archived goals, GOALS-archive.md, CHANGELOG - historical record, never retro-edited.

Test-pin inventory (2026-08-02 survey): BUILD-WARNING pinned in src/tests/modules/punkboot/utils/testsuites/utils/offsetstyle.test and src/tests/shell/testsuites/punkexe/maketclpayloadcheck.test; nobuild pinned in src/tests/shell/testsuites/punkexe/maketclbakelist.test; _build paths appear in punkexe maketclkitlocations/maketclhelp/maketclbakelist/maketclplatform tests, punkboot utils binaryarch/bootlibrary/offsetstyle tests and src/tests/modules/punkcheck/testsuites/punkcheck/install.test. The help SUMMARIES strings themselves ("Build .tm ...") are not test-pinned.

Propagation surfaces: canonical src/make.tcl -> 2 layout copies + templates modpod copy via the modules run (same channel as G-112); punk::mix edits -> src/bootsupport via the K4 dance; root .gitignore -> layout gitignore.in payloads via the G-012 sync; sibling repo tomlish carries its own src/make.tcl copy and lags until refreshed there.

Overlap survey 2026-08-02: goals_xref paths over src/make.tcl + src/modules/punk/mix + src/project_layouts + src/vfs/_config surfaced the make.tcl-wide goal set (df-damped shared-anchor scores); the real relationships are recorded below. goals_xref report's unlinked pairs do not involve this goal's surface beyond that shared anchor.

Related: G-112 (predecessor, archived - this goal extends its stage-true rename to the verb layer, tags and workdirs; see goals/archive/G-112-maketcl-subcommand-rename.md) Related: G-029 (title and mechanism carry the mint sense - coordinated retitle, proposal-first) Related: G-111 (active; prose references src/modules/_build staging - update rides this sweep) Related: G-028 (title/Goal use 'builds' for the bake/deploy act - coordinated wording when it activates) Related: G-110 + G-131 + G-137 (prose references src/_build / kit_builddir - adopt renamed paths at their landings) Related: G-023 + G-005 + G-006 + G-019 + G-026 + G-089 + G-136 (umbrella/module-stage/bake-domain 'build' prose named in the survey - live-tier non-contract wording rides this sweep; contract-line instances follow proposal-first at their own goals) Related: G-156 (follow-on, proposed 2026-08-02) - promotes this goal's identifier keep-list to a candidate work-list under the alpha-window rationale (no evidenced third-party consumers yet) with a machine-wide derived-project census; this goal's prose/tag/workdir sweep stands alone either way Related: G-035 + G-047 (2026-08-02 pre-activation score run) - same src/modules + src/lib AGENTS.md guidance surfaces and layout-seed/ignore-rule sync channels G-112's Notes recorded for both; their surfaces receive this sweep's vocabulary - coordinate edit windows if either activates concurrently

Follow-ons

Follow-on: promote the identifier keep-list to alpha-window renames with a derived-project census => goal G-156

19 KiB Raw Blame History