G-102 [proposed]: buildsuite bootstrap without a pre-existing tclsh - zig-driver hybrid

Direction agreed 2026-07-20: the whole buildsuite pipeline becomes
drivable with only the pinned zig toolchain present. Pre-tclsh phases
(fetch, configure-product generation, compile) move into the zig build
layer with sources in a content-hashed zon-shaped manifest (fossil
sources pin as per-checkin tarballs - '-refresh' becomes 'bump the pin';
fossil-checkout flow retained as the dev alternative); post-tclsh phases
(tcllib/tklib installers, critcl, parsed-totals test gate) stay Tcl
scripts run by the FRESHLY BUILT suite tclsh as build steps. Acceptance
includes a PATH-scrubbed no-tclsh end-to-end demonstration, preservation
of the copy-and-tweak retargeting property, and the recorded rejection of
a bash+powershell polyglot for this layer (polyglot craft remains the
acquisition layer's mechanism - punk-getzig/getpunk first contact).

Cross-references: G-096 direction note marked RESOLVED -> G-102 (its
remaining items close on the current suite.tcl shape regardless); G-099
sequencing now weighs birthing suite_tcl86 onto the chosen driver shape.
goals_lint clean (76 active, 26 archived).

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

GOALS.md

@@ -361,3 +361,7 @@ Detail: goals/G-100-suite-tcl86-tk-tcllib.md
 ### G-101 [proposed] kit container strategy for zig-built Tcl 8.6 runtimes (no zipfs)
 Scope: investigation + decision record under src/buildsuites/suite_tcl86/ (or successor mechanism), TEMP_REFERENCE/metakit + TEMP_REFERENCE/KitCreator (read-only guidance), src/runtime/mapvfs.config ('kit' type consumers), src/make.tcl kit-wrap path (as consumer)
 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

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

@@ -121,7 +121,7 @@ Acceptance: from a clean checkout plus a punk-getzig-fetched pinned zig, the sui
     need a tclsh - the FRESHLY BUILT suite tclsh serves as that intermediate.
   - Open question raised: long-term driver for the suite.tcl functionality - zig
     itself vs a cross-platform polyglot (bash+powershell as inputs). Current
-    recommendation (recorded from 2026-07-20 discussion, decision open): zig-driver
+    recommendation (recorded from 2026-07-20 discussion): zig-driver
     hybrid - pre-tclsh phases (fetch, configure-product generation, compile) migrate
     into the zig build layer (build.zig.zon is itself a declarative hashed source
     manifest, subsuming sources.config for zig-fetched trees); post-tclsh phases
@@ -129,6 +129,9 @@ Acceptance: from a clean checkout plus a punk-getzig-fetched pinned zig, the sui
     shell as build steps. Polyglot bash+powershell counselled against: two
     implementations (or a fragile dual-parse dialect) with divergent quoting/path
     semantics for exactly the string-heavy orchestration shells do worst.
+    RESOLVED 2026-07-20: user agreed with the zig-hybrid recommendation - drafted as
+    G-102 [proposed] (goals/G-102-buildsuite-zig-bootstrap.md). This goal's remaining
+    items close out on the current suite.tcl shape regardless.
 
 ## Progress
 

goals/G-099-suite-tcl86-buildsuite.md

@@ -44,7 +44,10 @@ SEQUENCING (2026-07-20 discussion): drafted as proposed while suite_tcl90 mature
 recommendation is to complete G-096's remaining items (TCLSH_PIPEREPL patch rebase +
 behaviour matrix, punk-getzig per-version fetch) and run the punk905_beta interactive
 trial through to promotion before activating this goal, so the shared suite
-scaffolding settles before it is forked.
+scaffolding settles before it is forked. Also weigh G-102 (zig-driver hybrid
+bootstrap, agreed direction 2026-07-20): its natural slot is before or alongside
+this goal so suite_tcl86 is born onto the chosen driver shape rather than ported
+later.
 
 ## Notes
 

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

@@ -0,0 +1,59 @@
+# G-102 buildsuite bootstrap without a pre-existing tclsh: zig-driver hybrid
+
+Status: proposed
+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)
+Goal: a buildsuite is drivable end-to-end with only the pinned zig toolchain present - no pre-existing tclsh anywhere in the chain. Pre-tclsh phases (source fetch, configure-product generation, compile) move into the zig build layer, with sources declared in a content-hashed declarative manifest (build.zig.zon or a zon-shaped equivalent) that keeps the copy-and-tweak retargeting property; post-tclsh phases (tcllib/tklib installers, critcl accelerators, the parsed-totals test gate, smokes) remain Tcl scripts executed by the FRESHLY BUILT suite tclsh as build steps - Tcl stays the tool exactly where a tclsh is guaranteed to exist because the suite just built it. The plain-tclsh suite.tcl remains as an ergonomic dev driver during transition (or is reduced to a thin documented wrapper).
+Acceptance: from a clean checkout plus the pinned zig (acquired via the consent-gated download mechanism or self-built), a documented zig invocation performs the whole pipeline in an environment where no pre-existing tclsh is resolvable (PATH-scrubbed demonstration recorded in this file): fetch/stage sources per the declarative manifest (content-integrity pins for zig-fetched trees; the fossil-checkout flow retained as a documented dev alternative for live-branch work), generate the configure-products, build the runtime, then run the post-tclsh phases under the suite-built shell - tcllib install with tcllibc accelerators via critcl, tklib, tk - and the expected-failure-baselined test gate, with results matching the suite.tcl-driven equivalents; the manifest is the documented tweak surface and copied suite trees remain isolated (G-096 copy-and-tweak property preserved); the recipe pins the zig version it is written against (API-churn mitigation - the 0.14->0.16 migration cost is the recorded precedent); the bash+powershell polyglot alternative for this layer is recorded as considered and rejected, with polyglot craft remaining the ACQUISITION layer's mechanism (punk-getzig/getpunk first-contact story).
+
+## Context
+
+Direction agreed 2026-07-20 (discussion recorded in G-096 notes; user decisions:
+toml dropped for binary buildsuites, long-term no-tclsh bootstrap intent, zig
+acquisition accepted as the root dependency, the freshly built tclsh accepted as
+the legitimate intermediate for tcllib/tklib installers and critcl).
+
+Why zig fits this layer:
+
+- build.zig.zon is itself a declarative, content-hashed source manifest - fetch by
+  url+hash gives declarative retargeting WITH integrity. Fossil sources pin as
+  per-checkin tarball urls (branch-tip tarballs are not hash-stable); that is a
+  provenance feature - '-refresh' becomes 'bump the pin' - with the fossil-checkout
+  path kept for dev-friendly live-branch work.
+- The recipe already generates configure-products (tclUuid.h, manifests, rc edits)
+  inside the zig layer - the boundary just extends to cover fetch.
+- zig Run steps execute artifacts they just built: 'zig build tcllib' = build tclsh
+  -> run installer.tcl under it; 'zig build test-gate' = run the core suite under it
+  and gate on parsed totals. The freshly-built-tclsh intermediate maps 1:1 onto the
+  build graph.
+
+Why NOT a bash+powershell polyglot for this layer (considered and rejected): the
+polyglot's value is first contact - zero installed tools - but the suite driver runs
+AFTER zig acquisition by definition, so a capable tool is always already present.
+The driver's workload (manifest parsing, byte-exact file generation, totals parsing,
+child-process orchestration) is what dual shell implementations do worst: two
+codebases in lockstep or a fragile dual-parse dialect, divergent quoting/path
+semantics as a permanent bug farm. Polyglot craft stays where it already earns its
+keep in this repo: the acquisition layer (punk-getzig / getpunk cmd-or-powershell
+first-contact twins).
+
+Residual external tools, and their long-term story: fossil and git CLIs are used by
+the current fetch flow. Under the zon path they become optional (tarball fetch with
+pinned hashes needs neither); fossil itself is buildable with zig cc if live
+checkouts without a preinstalled fossil are ever wanted.
+
+Relationships: G-005 (this formalizes its zig-build-infrastructure intent for the
+buildsuite path), G-006 (consent-gated artifact/toolchain download - the zig
+acquisition gate), G-018 (plain tclsh kits - substantially delivered by
+tclsh90szip.exe; reconciliation candidate), G-096 (origin discussion in its notes;
+the suite.tcl scaffolding this splits), G-099 (sequencing interplay below).
+
+SEQUENCING: proposed 2026-07-20. Natural slot is before or alongside G-099
+activation so suite_tcl86 is born onto the chosen driver shape rather than ported
+later - but this goal must not block G-096's remaining items (piperepl matrix,
+punk-getzig per-version fetch), which close out on the current suite.tcl shape.
+sources.config records are deliberately name/url/ref-shaped (close to zon records)
+so the manifest migration is mechanical.
+
+## Notes
+
+(none yet)