From edb33ded822f7adf0a44970277e78b4befdda80a Mon Sep 17 00:00:00 2001 From: Julian Noble Date: Sun, 2 Aug 2026 14:01:38 +1000 Subject: [PATCH] G-155 proposed: stage-true vocabulary part 2 (mint stage, strict build, _mint/_bake workdirs) User-directed draft from the 2026-08-02 build-terminology survey: - goals/G-155-mint-stage-vocabulary.md: contract (proposed), name-selection record (mint chosen; assemble/stage/install/emit/promote/package/mill rejected with reasons), drafted workflow_text TERMINOLOGY block, workdir rename plan (src/_bake kit assembly, per-srcdir _mint staging, buildsuites/_build unchanged), BAKE-WARNING retag, identifier keep-list (punkcheck installer identity, buildversion.txt, BUILDCOPY), test-pin inventory and propagation notes - GOALS.md: G-155 index entry appended (activation is a user decision) Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com --- GOALS.md | 4 + goals/G-155-mint-stage-vocabulary.md | 178 +++++++++++++++++++++++++++ 2 files changed, 182 insertions(+) create mode 100644 goals/G-155-mint-stage-vocabulary.md diff --git a/GOALS.md b/GOALS.md index fabbd52d..65660dfc 100644 --- a/GOALS.md +++ b/GOALS.md @@ -406,3 +406,7 @@ Detail: goals/G-150-cmdhelp-form-narrowing.md Scope: src/modules/punk/args-999999.0a1.0.tm (parse-result presentation); src/tests/modules/punk/args/testsuites/args/ Detail: goals/G-151-punkargs-annotated-success-render.md +### G-155 [proposed] Stage-true vocabulary part 2: mint stage named, build reserved for compiling, _mint/_bake workdirs +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) +Detail: goals/G-155-mint-stage-vocabulary.md + diff --git a/goals/G-155-mint-stage-vocabulary.md b/goals/G-155-mint-stage-vocabulary.md new file mode 100644 index 00000000..ae4f7c1e --- /dev/null +++ b/goals/G-155-mint-stage-vocabulary.md @@ -0,0 +1,178 @@ +# G-155 stage-true vocabulary part 2: mint stage named, build reserved for compiling, _mint/_bake workdirs + +Status: proposed +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 + /_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 + +To resolve at activation (G-112 pattern): + +- bakelist deployed-state token: nobuild -> nobake (recommended - bakelist is young (G-121, achieved - + see goals/archive/G-121-bakelist-selective-bake.md) and its consumers are in-repo tests) vs keep with + a recorded reason. Column-stable output contract either way. +- get_build_workdir -> get_bake_workdir proc rename: the folder rename works without it; renaming is an + API change that rides the bootsupport dance. Recommended: rename in the same pass (callers are + make.tcl + punk::mix only - verify at activation). +- BUILDCOPY punkcheck event + runtime_buildcopyname: recommended keep (recorded punkcheck vocabulary); + BAKECOPY only with a future punkcheck format change. +- G-029 retitle exact wording ("Mint packaged test:: #modpod modules from src/tests") - + proposal-first at that goal's entry. +- Whether README/ARCHITECTURE get a terminology pointer line or the block stays workflow_text-only + (recommended: workflow_text canonical + one-line pointers). + +## 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 -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 /_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/. +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)