Browse Source

contextual sweep: deprecated make.tcl subcommand references (user-directed, incl. contract lines)

Each site read in context, not grep-replaced; bakehouse vs bake chosen per
meaning, and missing invocation arguments supplied where the reference
describes an unattended flow:
- G-005 Approach + Notes, G-006 Acceptance + body: 'make.tcl project' ->
  'make.tcl bakehouse' (the full consumer build these goals integrate with;
  no flags - conceptual references on a clean checkout, not recipes).
- G-057 Acceptance: 'make.tcl project' -> 'make.tcl bake' (icon embedding
  lives in the kit-wrap stage and must hold for a bare bake; bakehouse
  inherits).
- G-028 Context DELIBERATELY UNCHANGED: dated 2026-07-07 incident narrative -
  the command actually run; history stays verbatim (alias keeps it readable).
- src/runtime/mapvfs.config todo: 'vfs' -> 'bake' wish, re-annotated - G-104
  achieved WITHOUT the single-kit-by-name/list-kits item (still open).
- src/runtime/vendorlib_vfs.toml header: vfslibs now runs as a phase of bake
  (G-112 fold), not 'as part of project'.
- shellexit.test + staticruntime.test rebuild comments: 'project' -> 'bake'
  AND stale '(interactive y confirmation)' / bare vfscommonupdate corrected to
  '-confirm 0' (piped y retired since G-030) - the missing-arguments class.
- punk.project layout store vfs READMEs (lib + modules): 'make.tcl vfs' ->
  'make.tcl bake'; modpod template twins propagated via the punkcheck
  layout->modpod sync (make.tcl modules run), never hand-edited.
Variant-phrasing sweep confirmed non-hits: G-115 '(vfs assembly)' names the
src/vfs payload tier (name retained), G-047 'make.tcl/project.new' is the dev
project.new command. Archive tier + CHANGELOG history untouched.
goals_lint + goals_xref refs clean.

Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
master
Julian Noble 6 days ago
parent
commit
232f2f6096
  1. 4
      goals/G-005-zig-build-infrastructure.md
  2. 4
      goals/G-006-prebuilt-artifact-download.md
  3. 2
      goals/G-057-kit-icon-embedding.md
  4. 2
      src/modules/punk/mix/#modpod-templates-999999.0a1.0/templates/project_layouts/vendor/punk/project-0.1/src/vfs/project.vfs/lib/README.md
  5. 2
      src/modules/punk/mix/#modpod-templates-999999.0a1.0/templates/project_layouts/vendor/punk/project-0.1/src/vfs/project.vfs/modules/README.md
  6. 2
      src/project_layouts/vendor/punk/project-0.1/src/vfs/project.vfs/lib/README.md
  7. 2
      src/project_layouts/vendor/punk/project-0.1/src/vfs/project.vfs/modules/README.md
  8. 4
      src/runtime/mapvfs.config
  9. 6
      src/runtime/vendorlib_vfs.toml
  10. 3
      src/tests/shell/testsuites/punkexe/shellexit.test
  11. 2
      src/tests/shell/testsuites/punkexe/staticruntime.test

4
goals/G-005-zig-build-infrastructure.md

@ -24,7 +24,7 @@ This goal is the primary mechanism for G-004's outcome. It is independent of and
2. **Expand to other dependencies.** Extend the zig build to cover the other native binary dependencies currently committed (twapi, tcllibc, etc.), one at a time. Each dependency gets a zig build target that produces the same artifact shape the repo currently commits.
3. **Integrate with make.tcl.** `tclsh src/make.tcl` is the existing build entry point. Wire it so that when a required binary artifact is not present, it invokes the zig build to produce it (or, per G-006, offers the download path). The integration must not require a separate manual zig step for a normal `make.tcl project` build when the zig toolchain is available.
3. **Integrate with make.tcl.** `tclsh src/make.tcl` is the existing build entry point. Wire it so that when a required binary artifact is not present, it invokes the zig build to produce it (or, per G-006, offers the download path). The integration must not require a separate manual zig step for a normal `make.tcl bakehouse` build when the zig toolchain is available.
4. **Document the zig toolchain prerequisite.** The zig toolchain is a build-time prerequisite for this path. Document how to obtain it (install instructions, version pinning). Consider auto-detection with an actionable message when zig is absent, and defer to G-006's download path or an error depending on what the user has configured.
@ -55,7 +55,7 @@ This goal is the primary mechanism for G-004's outcome. It is independent of and
G-116 - is the arm's-length runtime factory this goal's direction became, sharing the
pinned-zig / zig-only toolchain policy. This goal's distinct remainder: building the
VENDORED native extensions (twapi, tcllibc class) and wiring missing-binary retrieval
into the normal make.tcl project build; G-116 is the living edge of that
into the normal make.tcl bakehouse build; G-116 is the living edge of that
extension-build expansion list. Status note: much of this goal's Tcl-core substance
has landed through the archived arc while this file stays `proposed` - the goal's
currency/scope (vendored deps + make.tcl integration vs the suites' runtime-factory

4
goals/G-006-prebuilt-artifact-download.md

@ -3,7 +3,7 @@
Status: proposed
Scope: src/runtime/; src/make.tcl integration; user-config (consent flags)
Goal: pre-built binary artifacts can be downloaded from a separate related binary-artifacts repository or user-configured sources, gated by explicit user consent/configuration by default.
Acceptance: a download mechanism fetches binary artifacts (the same set the zig build produces) from a configured source on demand; by default the download is gated behind explicit user consent (a config flag or interactive prompt) and does not occur silently; a user-configured source URL overrides the default binary-artifacts repo; downloaded artifacts satisfy the same build requirements as zig-built artifacts so `tclsh src/make.tcl project` succeeds with downloaded artifacts in place of built ones.
Acceptance: a download mechanism fetches binary artifacts (the same set the zig build produces) from a configured source on demand; by default the download is gated behind explicit user consent (a config flag or interactive prompt) and does not occur silently; a user-configured source URL overrides the default binary-artifacts repo; downloaded artifacts satisfy the same build requirements as zig-built artifacts so `tclsh src/make.tcl bakehouse` succeeds with downloaded artifacts in place of built ones.
## Context
@ -25,7 +25,7 @@ This goal is parallel to and independent of G-005. A user with zig uses G-005; a
3. **Source configuration.** A config value for the artifact source URL, defaulting to the separate binary-artifacts repo. A user-configured value overrides the default. Document the config key and the expected source format (URL layout, artifact naming convention).
4. **Integration with make.tcl.** When `make.tcl` needs a binary artifact that isn't present and the zig build path (G-005) is not available or not chosen, the download path is offered/followed per the consent gate. The integration must make `tclsh src/make.tcl project` succeed with downloaded artifacts in place of built ones — the artifacts are interchangeable from the build's perspective.
4. **Integration with make.tcl.** When `make.tcl` needs a binary artifact that isn't present and the zig build path (G-005) is not available or not chosen, the download path is offered/followed per the consent gate. The integration must make `tclsh src/make.tcl bakehouse` succeed with downloaded artifacts in place of built ones — the artifacts are interchangeable from the build's perspective.
5. **Artifact equivalence.** Downloaded artifacts must satisfy the same build requirements as zig-built ones (same file shape, same location, same version). If a downloaded artifact differs in a way the build cares about (e.g. different Tcl9 patchlevel), the build must detect and reject it rather than producing a subtly broken system.

2
goals/G-057-kit-icon-embedding.md

@ -3,7 +3,7 @@
Status: proposed
Scope: src/make.tcl (kit/zipkit wrap steps); src/runtime/punk1.ico (project default, existing); src/vfs/*.vfs (override placement convention); src/runtime/mapvfs.config (only if an explicit config element is the chosen override mechanism); TEMP_REFERENCE/tcl-sfe (read-only reference); helper proc location decided in the work (make.tcl inline vs punk::mix lib)
Goal: Windows kit/zipkit builds produce executables carrying an embedded icon chosen at build time - defaulting to the project icon src/runtime/punk1.ico, overridable per kit by its .vfs folder - by replacing the icon resources in the built executable using the twapi-based mechanism demonstrated in tcl-sfe (TEMP_REFERENCE/tcl-sfe, by twapi author and Tcl core member Ashok P. Nadkarni): RT_ICON/RT_GROUP_ICON replacement via twapi resource-update APIs, applied so the appended vfs payload stays intact (icon the stub before appending, or sfe-style split/update/reattach).
Acceptance: a Windows `make.tcl project` build produces kit executables whose embedded icon resources are the project default punk1.ico, and a kit whose .vfs supplies an override icon gets that icon instead (verified by resource inspection, e.g twapi::extract_resources, not just Explorer eyeballing); the icon-replaced executables still boot to a working punk shell reading their vfs payload for the kit types we build (kit, zip, zipcat per mapvfs.config); runtimes under src/runtime are never modified - replacement applies to the built copies only; twapi unavailable or non-Windows platform skips the icon step with a notice and the build otherwise completes unchanged; rebuilds are idempotent (re-wrapping an already-iconed build copy converges, no resource accumulation); the override convention (filename/location in the kit's custom .vfs folder vs a mapvfs.config element) and the stub-vs-split ordering decision are recorded in the detail file with the tcl-sfe attribution.
Acceptance: a Windows `make.tcl bake` build produces kit executables whose embedded icon resources are the project default punk1.ico, and a kit whose .vfs supplies an override icon gets that icon instead (verified by resource inspection, e.g twapi::extract_resources, not just Explorer eyeballing); the icon-replaced executables still boot to a working punk shell reading their vfs payload for the kit types we build (kit, zip, zipcat per mapvfs.config); runtimes under src/runtime are never modified - replacement applies to the built copies only; twapi unavailable or non-Windows platform skips the icon step with a notice and the build otherwise completes unchanged; rebuilds are idempotent (re-wrapping an already-iconed build copy converges, no resource accumulation); the override convention (filename/location in the kit's custom .vfs folder vs a mapvfs.config element) and the stub-vs-split ordering decision are recorded in the detail file with the tcl-sfe attribution.
## Context

2
src/modules/punk/mix/#modpod-templates-999999.0a1.0/templates/project_layouts/vendor/punk/project-0.1/src/vfs/project.vfs/lib/README.md vendored

@ -4,4 +4,4 @@ pkgIndex.tcl-based libraries to embed in the runtime kit built from this vfs fol
This layout ships no library snapshot. Populate this folder with the libraries your
kit runtime needs (for example by copying from a punk shell distribution or your
project's built lib folders) before building a kit with 'make.tcl vfs'.
project's built lib folders) before building a kit with 'make.tcl bake'.

2
src/modules/punk/mix/#modpod-templates-999999.0a1.0/templates/project_layouts/vendor/punk/project-0.1/src/vfs/project.vfs/modules/README.md vendored

@ -4,4 +4,4 @@ Tcl .tm modules to embed in the runtime kit built from this vfs folder.
This layout ships no module snapshot. Populate this folder with the modules your
kit runtime needs (for example by copying from a punk shell distribution or your
project's built modules folders) before building a kit with 'make.tcl vfs'.
project's built modules folders) before building a kit with 'make.tcl bake'.

2
src/project_layouts/vendor/punk/project-0.1/src/vfs/project.vfs/lib/README.md vendored

@ -4,4 +4,4 @@ pkgIndex.tcl-based libraries to embed in the runtime kit built from this vfs fol
This layout ships no library snapshot. Populate this folder with the libraries your
kit runtime needs (for example by copying from a punk shell distribution or your
project's built lib folders) before building a kit with 'make.tcl vfs'.
project's built lib folders) before building a kit with 'make.tcl bake'.

2
src/project_layouts/vendor/punk/project-0.1/src/vfs/project.vfs/modules/README.md vendored

@ -4,4 +4,4 @@ Tcl .tm modules to embed in the runtime kit built from this vfs folder.
This layout ships no module snapshot. Populate this folder with the modules your
kit runtime needs (for example by copying from a punk shell distribution or your
project's built modules folders) before building a kit with 'make.tcl vfs'.
project's built modules folders) before building a kit with 'make.tcl bake'.

4
src/runtime/mapvfs.config

@ -65,7 +65,9 @@ tclsfe-x64.exe {punk9wintk903.vfs punk91 zip}
#_beta convention: wrap freshly suite-built runtimes as *_beta kits even BEFORE they have passed the
# punk test suites - so new-runtime behaviour can be trialled interactively. Drop _beta on acceptance.
# (punk905_beta trialled and PROMOTED to punk905 2026-07-21.)
#todo: 'make.tcl vfs' enhancement - build a single configured kit by name + list configured kits (G-104)
#todo: 'make.tcl bake' enhancement - build a single configured kit by name + list configured kits
# (sibling-ergonomics wish recorded in G-104, achieved 2026-07-25 WITHOUT this item -
# see goals/archive/G-104-maketcl-buildsuite-surface.md; still open)
#5
tclsh905.exe {punk9wintk905.vfs punk905 zip}

6
src/runtime/vendorlib_vfs.toml

@ -2,8 +2,10 @@
#
# Declares which vendored platform-library package folders (paths relative to src/) are
# installed into which kit vfs lib trees (paths relative to src/vfs/). Processed by
# 'tclsh src/make.tcl vfslibs' - and automatically as part of 'tclsh src/make.tcl project' -
# with punkcheck-tracked provenance (records in src/vfs/.punkcheck, outside kit payloads).
# 'tclsh src/make.tcl vfslibs' - and automatically as a phase of 'tclsh src/make.tcl bake'
# (and therefore of 'bakehouse'; G-112 folded the phase in so a bake cannot ship stale
# binary libs) - with punkcheck-tracked provenance (records in src/vfs/.punkcheck,
# outside kit payloads).
#
# Participation is per-package per-kit by design: kit vfs package sets intentionally differ
# (e.g. twapi versions vary per kit), so nothing is blanket-copied and a vendorlib drop does

3
src/tests/shell/testsuites/punkexe/shellexit.test

@ -20,7 +20,8 @@ package require tcltest
#then <projectroot>/bin/punkshell902. Tests are skipped (constraint punkexeavailable) if none found.
#
#NOTE: the tests exercise the BUILT executable - after changing punk::repl or app-punkshell source, rebuild
#with 'make.tcl packages', then 'make.tcl vfscommonupdate' (interactive y confirmation), then 'make.tcl project'
#with 'make.tcl packages', then 'make.tcl vfscommonupdate -confirm 0' (unattended; the REPLACE confirmation
#aborts fast on non-interactive stdin - piped y is retired), then 'make.tcl bake'
#or these tests will run against a stale binary.
#
#WARNING for interactive runs: a regression in the eof/error termination path causes the spawned executable

2
src/tests/shell/testsuites/punkexe/staticruntime.test

@ -17,7 +17,7 @@ package require tcltest
#sha1sums.txt) - retrieve to bin/runtime/<platform>/ and rebuild.
#
#NOTE: tests exercise the BUILT executable - after changing punk_main.tcl or the seeding
#modules, rebuild with 'make.tcl modules', 'make.tcl vfscommonupdate', 'make.tcl project'
#modules, rebuild with 'make.tcl modules', 'make.tcl vfscommonupdate -confirm 0', 'make.tcl bake'
#or these tests will run against a stale binary.
namespace eval ::testspace {

Loading…
Cancel
Save