G-103..G-105 [proposed]: runtime kit family, make.tcl buildsuite surface, cross-target builds

User requirements batch 2026-07-20 integrated:

- G-103 runtime kit family: buildsuites produce self-contained kits whose
  info library and batteries live in the initially attached zip - PLAIN
  tclsh kit (Thread + tclvfs/vfs::* + tcllib/tcllibc), PUNK kit (piperepl
  applied, ENABLED BY DEFAULT with env opt-out - gating review agreed; the
  plain kit serves stock semantics), BI kits adding libraries we build (Tk
  now; sqlite3/tdom easy/moderate futures; twapi flagged needs-investigation
  under the zig-only policy). tcllib+tcllibc in all members (user lean,
  agreed). Artifact metadata in punkbin (+compatible repos) surfaced by the
  runtime scriptset list/use. G-018 flagged as substantially subsumed. 8.6
  variant deferred through G-101 (static-vfs/metakit questions noted there).
- G-104 make.tcl buildsuite surface: list / info <suite> / build <suite>
  with suites SELF-describing (info contract survives the G-102 driver
  migration; copied trees appear automatically). mapvfs single-kit/list
  wishes noted as sibling ergonomics.
- G-105 cross-target builds: -target as an invocation dimension (suite
  folders stay version-named), linux x86_64 first verified via local WSL
  with its own test baseline; zig tier findings VERIFIED and recorded -
  the freebsd asymmetry suspicion is inverted (freebsd AS TARGET was the
  gap, closed in zig 0.16 for FreeBSD 14+ with CI-tested x86_64/aarch64;
  building FROM freebsd was already fine); macOS-as-target (SDK/frameworks)
  recorded as the hard case; fully-static-musl dlopen limitation drives a
  dynamic first linux target.

Cross-edits: G-096 piperepl matrix gains the kit-default policy update
(punk kits opt-out not opt-in); G-101 records the 8.6 kit-family
dependency; G-102 notes the family/target/surface as build-graph products.
goals_lint clean.

Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com

GOALS.md

@@ -365,3 +365,15 @@ Detail: goals/G-101-tcl86-kit-container-strategy.md
 ### G-102 [proposed] buildsuite bootstrap without a pre-existing tclsh: zig-driver hybrid
 Scope: src/buildsuites/suite_tcl90/ (driver split: zig-layer fetch/generate/compile + suite-tclsh-run Tcl phases; sources.config -> zon-shaped manifest migration), src/buildsuites/ (the pattern future suites fork - interplay with G-099), bin/tools/ (pinned zig acquisition per the consent-gated mechanism), src/scriptapps/bin/ punk-getzig (acquisition layer, unchanged in role)
 Detail: goals/G-102-buildsuite-zig-bootstrap.md
+
+### G-103 [proposed] runtime kit family from buildsuites: plain / punk / bi kits with attached batteries + artifact metadata
+Scope: src/buildsuites/suite_tcl90/ (kit assembly steps in recipe/driver; pattern for later suites), src/vfs/_config + src/runtime/mapvfs.config (as consumers of the new runtime names), punkbin repo layout + metadata (c:/repo/jn/punkbin; compatible repos), src/scriptapps runtime scriptset ('runtime.cmd' list/use - punk-runtime rename pending G-097), goals/G-018 (subsumption review)
+Detail: goals/G-103-runtime-kit-family.md
+
+### G-104 [proposed] make.tcl buildsuite surface: list / info / build
+Scope: src/make.tcl (buildsuite subcommand group), src/buildsuites/*/ (suite self-description contract: an 'info'/describe affordance per suite - suite.tcl action or manifest record), documentation (make.tcl help text, src/buildsuites README/AGENTS)
+Detail: goals/G-104-maketcl-buildsuite-surface.md
+
+### G-105 [proposed] buildsuite cross-target builds (zig -target): linux first, WSL-verified
+Scope: src/buildsuites/suite_tcl90/ (target parameterization of recipe + driver; per-target out prefixes), src/buildsuites/ (layout/naming decision: target is an INVOCATION DIMENSION, suite folders stay version-named - no per-target tree copies), bin/runtime platform-dir naming alignment (punkshell's win32-x86_64-style names vs zig triples), punkbin per-target artifact layout (with G-103 metadata carrying the target), local WSL as the first cross-verification environment
+Detail: goals/G-105-buildsuite-cross-target.md

goals/G-096-zig-buildsuite-piperepl.md

@@ -300,4 +300,9 @@ Remaining for acceptance:
   tty/piped/script-arg forms; =1 with a script setting ::tclsh(dorepl) 1 -> live
   interactive console repl after piped eof with unconsumed input in
   ::tclsh(inputbuffer)).
+  KIT-DEFAULT POLICY UPDATE (2026-07-20, G-103): with a kit FAMILY the env gating
+  flips for punk kits - the patch is applied and ENABLED BY DEFAULT there (env
+  opt-OUT, e.g TCLSH_PIPEREPL=0), while the PLAIN family member carries no patch
+  for stock semantics. The matrix above still characterizes the patch itself on
+  the patched binary; restate it in opt-out terms when the variant lands.
 - Final clean-checkout re-verification of the whole flow once the above land.

goals/G-101-tcl86-kit-container-strategy.md

@@ -25,6 +25,12 @@ zip-wrap). 8.6 has no zipfs, so a kit needs a vfs container and a boot mechanism
 make.tcl's existing 'kit' wrap type drives sdx/mk4-style wrapping; whichever
 container is chosen must either fit that path or come with a documented successor.
 
+The G-103 runtime kit family (plain/punk/bi kits with thread + tclvfs + tcllib
+batteries in the attached container) extends to 8.6 THROUGH this investigation: the
+user notes (2026-07-20) that in the 8.6 case tclvfs may have to be STATIC and there
+may be metakit-specific patching - both are part of this goal's assessment, and the
+8.6 family variant is blocked on its outcome.
+
 Separated from G-099/G-100 deliberately: runtime + libs + test gating are
 well-understood ports of the 9.0 work, while this is open investigation - keeping
 it out of their acceptance keeps the 8.6 suite arc incrementally landable.

goals/G-102-buildsuite-zig-bootstrap.md

@@ -56,4 +56,8 @@ so the manifest migration is mechanical.
 
 ## Notes
 
-(none yet)
+- 2026-07-20 (user requirements batch): the build-graph products this driver shape
+  must express grew concrete - the G-103 runtime kit FAMILY (plain/punk/bi kits with
+  attached batteries) become named build outputs, G-105 adds -target as a build
+  dimension, and G-104's make.tcl surface fronts whichever driver shape wins (its
+  suite self-description contract must survive the migration).

goals/G-103-runtime-kit-family.md

@@ -0,0 +1,50 @@
+# G-103 runtime kit family from buildsuites: plain / punk / bi kits with attached batteries + artifact metadata
+
+Status: proposed
+Scope: src/buildsuites/suite_tcl90/ (kit assembly steps in recipe/driver; pattern for later suites), src/vfs/_config + src/runtime/mapvfs.config (as consumers of the new runtime names), punkbin repo layout + metadata (c:/repo/jn/punkbin; compatible repos), src/scriptapps runtime scriptset ('runtime.cmd' list/use - punk-runtime rename pending G-097), goals/G-018 (subsumption review)
+Goal: buildsuites produce a defined FAMILY of runnable, self-contained runtime kits - executables whose info library and core batteries live in the initially attached zip, depending on no external filesystem tree: (1) a PLAIN tclsh kit carrying loadable Thread, tclvfs with as many vfs::* packages as we have, and tcllib+tcllibc; (2) a PUNK kit = the plain kit with the TCLSH_PIPEREPL patch applied and ENABLED BY DEFAULT (env opt-out, not opt-in - users wanting stock behaviour take the plain kit); (3) BI (batteries-included) punk kits additionally carrying libraries WE BUILD - Tk first; sqlite3/tdom/twapi as future build targets - all in the attached zip. These are the project's 'runtime' executables: punkbin candidates carrying metadata (variant, component versions, target platform, provenance) that runtime list/use subcommands can surface.
+Acceptance: suite_tcl90 produces named artifacts for at least plain, punk, and one bi (+Tk) kit; each verified self-contained from a path with no external Tcl visible (info library resolves into the attached zip; package require checks for Thread, vfs + representative vfs::* packages, tcllib module + tcllibc acceleration engaged; bi adds Tk create/destroy) with the checks recorded here; the punk kit demonstrates piperepl active by default and disabled via the documented env opt-out, the plain kit demonstrates stock behaviour (no patch); artifact metadata (variant, versions, target, source provenance) is emitted alongside the binaries in the punkbin layout and surfaced by the runtime scriptset's list/use; the naming scheme for family members is documented and mapvfs.config consumes the punk/bi runtimes; the 8.6 family variant is explicitly deferred to the G-101 container investigation (static vfs / metakit patching questions).
+
+## Context
+
+User requirements 2026-07-20. Formalizes and extends what suite_tcl90 half-delivers:
+tclsh90szip.exe already attaches the tcl library (self-contained info library ✓) but
+thread/tclvfs/tcllib ride outside (out/lib or the punk .vfs payload) - the note from
+G-098 (achieved 2026-07-20), "future: attach at least tclvfs & thread to the
+runtime's own zip", becomes a
+requirement here, extended to tcllib+tcllibc for all family members (user lean,
+agreed: tcllib is widely used and tcllibc's speedup makes bootstrapping and other
+usecases far more practical; zip compression keeps the cost modest - a leaner
+variant remains possible later via configuration rather than a separate philosophy).
+
+piperepl gating REVIEW (user 2026-07-20): the patch's original env gating
+(TCLSH_PIPEREPL=1 opt-in) fit a single-binary world. With a kit FAMILY the punk kits
+are FOR punk use - default ON, env opt-OUT (e.g TCLSH_PIPEREPL=0) for debugging;
+the plain kit exists for those who want stock semantics. G-096's behaviour-matrix
+item still characterizes the patch itself; its kit-default policy is restated there
+pointing here.
+
+Family boundary: bi kits carry libraries WE BUILD (zig-only policy) - not vendored
+third-party binaries. Tk is built today; sqlite3 is a straightforward future build
+(amalgamation compiles cleanly under zig cc); tdom moderate; twapi historically
+MSVC-leaning - its buildability under the zig-only policy needs investigation before
+it can join a bi kit (until then twapi remains a kit-vfs vendored payload as in
+punk9wintk903.vfs, outside this family's attached-zip guarantee).
+
+Metadata format note: toml is acceptable HERE (runtime list/use run in punkshell
+contexts where vendored tomlish exists) - the 2026-07-20 toml drop applies to
+BUILDSUITE BOOTSTRAP configs which must parse dependency-free, a distinct concern.
+punkbin currently carries sha1sums.txt (+ minisign) - metadata extends, not
+replaces, that. Compatible repos (punkbin mirrors) carry the same records.
+
+Relationships: G-018 (zig plain tclsh kits) is substantially subsumed by the plain
+family member - reconciliation/retirement decision flagged for the user. G-102
+(zig-driver hybrid): the family members become named build-graph products. G-105
+(cross-target): family x target is the punkbin artifact matrix - metadata carries
+the target dimension. G-101: the 8.6 family variant depends on the container
+strategy. G-006: punkbin download consent. G-097: runtime.cmd -> punk-runtime
+rename interplay.
+
+## Notes
+
+(none yet)

goals/G-104-maketcl-buildsuite-surface.md

@@ -0,0 +1,35 @@
+# G-104 make.tcl buildsuite surface: list / info / build
+
+Status: proposed
+Scope: src/make.tcl (buildsuite subcommand group), src/buildsuites/*/ (suite self-description contract: an 'info'/describe affordance per suite - suite.tcl action or manifest record), documentation (make.tcl help text, src/buildsuites README/AGENTS)
+Goal: an ergonomic make.tcl surface for defined buildsuite builds: 'make.tcl buildsuite list' discovers the suites under src/buildsuites (excluding _build and non-suite dirs) with one-line descriptions; 'make.tcl buildsuite info <name>' surfaces the configured detail for review - source records from sources.config (urls/refs/pins), the pinned zig, the product set, doc pointers; 'make.tcl buildsuite build <name> ?args?' runs the suite's driver forwarding suite options (e.g -tclbranch, -refresh, -target when G-105 lands). Suites stay SELF-describing so copy-and-tweak trees (G-096 workflow) appear in list/info automatically without make.tcl edits.
+Acceptance: list shows suite_tcl90 (and any copied tree) with descriptions sourced from the suites themselves; info renders the sources.config-derived table plus zig pin and products for a named suite; build forwards arguments and streams driver output, exiting with the driver's status; the surface works when make.tcl runs under a plain tclsh and under punk kit executables; help text documents the group; the self-description contract is documented where suite authors will find it (src/buildsuites docs) and holds for a tree created by copying suite_tcl90.
+
+## Context
+
+User requirement 2026-07-20: "an ergonomic way to run a defined buildsuite build -
+nice-to-have is a way to list possible builds and considering there is a fair bit of
+configured info for each, a way to retrieve/review info about a particular
+buildsuite. Presuming surface will be a subcommand or group of subcommands in
+make.tcl."
+
+Design lean: make.tcl stays a THIN front - discovery by directory scan, description
+and info answered by the suite itself (a 'suite.tcl info' action emitting a stable
+record, or a small manifest the driver also reads). That keeps copied/retargeted
+trees first-class citizens and survives the G-102 driver-shape migration (whatever
+replaces suite.tcl keeps answering the same contract; make.tcl need not know which
+shape a suite uses).
+
+Sibling ergonomics note: the earlier-recorded make.tcl 'vfs' wishes (build a single
+configured kit by name + list configured kits from mapvfs.config - noted in
+mapvfs.config comments and archived G-098 (achieved 2026-07-20) notes) are a
+separate subsystem (kit wrapping) but the same ergonomic family - a candidate to
+execute alongside this goal.
+
+Relationships: G-096 (suite.tcl driver + copy-and-tweak workflow this fronts),
+G-102 (driver shape - the info/build contract must survive it), G-103 (family
+products appear in info output), G-105 (target dimension forwarded when it exists).
+
+## Notes
+
+(none yet)

goals/G-105-buildsuite-cross-target.md

@@ -0,0 +1,42 @@
+# G-105 buildsuite cross-target builds (zig -target): linux first, WSL-verified
+
+Status: proposed
+Scope: src/buildsuites/suite_tcl90/ (target parameterization of recipe + driver; per-target out prefixes), src/buildsuites/ (layout/naming decision: target is an INVOCATION DIMENSION, suite folders stay version-named - no per-target tree copies), bin/runtime platform-dir naming alignment (punkshell's win32-x86_64-style names vs zig triples), punkbin per-target artifact layout (with G-103 metadata carrying the target), local WSL as the first cross-verification environment
+Goal: buildsuites accept a target parameter (zig -target triple) producing isolated per-target outputs from the same suite tree, with the first cross target being linux x86_64 verified end-to-end using the local WSL: the cross-built tclsh (plus at least thread and tclvfs) runs there, executes scripts, loads its packages, and a core-testsuite run under WSL is recorded against its own expected-failure baseline. The layout/naming decision for buildsuites and artifact dirs is made and documented so later targets (freebsd, aarch64 variants) slot in without restructuring.
+Acceptance: a documented suite invocation with a target argument produces out/<target>/ (or equivalent isolated prefix) without disturbing the native build; the linux tclsh runs under the local WSL executing a script and package require checks for thread/vfs (recorded here); a core-test run under WSL is gated against a tracked linux baseline (separate from the windows baseline; dispositioned entries); dynamic-extension loading works on the chosen linux flavour (the fully-static-musl 'load' limitation is the recorded reason the first target is dynamic - x86_64-linux-gnu with a pinned glibc floor, or musl-dynamic - decision + rationale recorded at activation); folder/naming decisions (suite dirs version-named, target as parameter; platform-name mapping between punkshell dirs and zig triples) are documented; punkbin layout accommodates the target dimension with G-103 metadata.
+
+## Context
+
+User requirement 2026-07-20: "We will eventually want to use zig's cross-platform
+build capabilities - a first target might be for linux - something we can test with
+our local wsl. This has implications for how we structure/name the folders under
+buildsuites." Current linux runtime is a prebuilt tclkit (mapvfs.config:
+tclkit-902-Linux64-intel-dyn -> punkshell902 kit) - same provenance gap the suites
+close on windows.
+
+zig platform-tier findings (verified 2026-07-20 - the user's asymmetry suspicion is
+INVERTED):
+
+- Windows/linux AS TARGETS ship their libcs with zig on every host (mingw-w64,
+  glibc stubs, musl) - building them FROM freebsd/macos/etc is supported; the host
+  mostly doesn't matter for punkshell's primary pair.
+- FreeBSD AS A TARGET was the historically missing piece: zig 0.16 added
+  cross-compilation to FreeBSD 14+ (stub dynamic libc a la glibc; x86_64-freebsd and
+  aarch64-freebsd now tested in zig's CI). Note zig still DEFAULTS to freebsd 13 -
+  the triple must pin >=14 for cross builds.
+- macOS AS A TARGET is the genuinely hard case: Apple SDK/frameworks are not shipped
+  with zig (licensing) - anything linking system frameworks (Tk/Aqua!) needs an SDK
+  arrangement. Out of scope here; recorded so nobody assumes triple-swap suffices.
+- linux dlopen caveat driving the first-target choice: a fully-static musl build
+  cannot usefully 'load' shared extensions - a tclsh that loads thread/vfs dlls
+  wants dynamic linking (glibc-stub dynamic with a chosen version floor, or
+  musl-dynamic).
+
+Relationships: G-060 (qemu cross-platform matrix - WSL is the cheap first rung;
+qemu covers what WSL cannot), G-099/G-100 (the 8.6 suite inherits the target
+dimension), G-102 (driver shape: target becomes a build-graph dimension), G-103
+(family x target = the punkbin artifact matrix), G-006 (punkbin artifact consent).
+
+## Notes
+
+(none yet)