Browse Source
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.commaster
2 changed files with 182 additions and 0 deletions
@ -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 <projectdir>" (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 + <pkg>-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/<platform>/ 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/<srcdirname> 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/<exe>.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::<modulename> #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 <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. |
||||||
|
- <pkg>-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) |
||||||
Loading…
Reference in new issue