# src/buildsuites - Buildsuites (zig runtime factory)

## Purpose

Suites that build Tcl runtimes and binary companions from external upstream
sources using the pinned zig toolchain (zig-only build policy). Arm's-length
from the project build/bake stages: inputs are upstream checkouts/pins, not
this project's `src/` tree.

## Ownership

- Suite trees (`suite_tcl90/`, future `suite_tcl86/` etc) are agent-editable
  under user-directed goal work (the G-096/G-099 arcs).
- `_build/` is a VCS-ignored build area - never commit from it; each suite
  stages into `_build/<suitename>`.

## Local Contracts

- The suite self-description contract (what makes a directory a suite, the
  `sources.config` record grammar incl. description/product/doc/zigpin, the
  copy-and-tweak guarantee) is documented in `README.md` here - keep it and
  the `make.tcl buildsuite` surface in step.
- `sources.config` is parsed, never executed - by both the suite driver and
  `make.tcl buildsuite list/info`. Grammar changes must land in both parsers
  (suite.tcl strict, make.tcl tolerant) plus `README.md`.
- Fossil clones live in the machine-level store (`PUNK_FOSSIL_STORE`, default
  `~/.punkshell/fossils`) - outside `_build`-class deletable dirs.
- Suite drivers must keep working when invoked directly (`tclsh suite.tcl ...`)
  AND via `make.tcl buildsuite build <name>` (which forwards args untouched).

## Verification

- `tclsh src/make.tcl buildsuite list` shows every suite with its description.
- `tclsh src/make.tcl buildsuite info <name>` renders the manifest-derived
  detail for the touched suite.
- Suite pipelines verify per their own README/goal records (test gates vs
  tracked expected_test_failures baselines).

## Child DOX Index

- `suite_tcl90/` - Tcl 9.0 suite (its README.md carries lineage/detail,
  including the G-138 `library-artifacts` punkbin lib-tier emission and the
  G-140 `tcllibc-linux` cross lane - critcl driving zig cc -target for the
  linux-x86_64 lib tier, ELF-gated on the windows host; no child AGENTS.md
  yet)
- `suite_tcl86/` - Tcl 8.6 suite (G-099 achieved 2026-07-26: tclsh86ts/tclsh86t
  + tcl86t.dll + lib tree, thread 2.8.13 + tclvfs 1.4.2, core/thread/tclvfs
  gates; G-100 achieved 2026-07-26: Tk 8.6.17 + tklib 0.9 + tcllib 2.0/tcllibc,
  and punkshell's own runtests censused on this runtime; G-138
  `library-artifacts` emits the tcl8-generation punkbin lib tier). Its README.md
  carries the deliverables, source selections, both makefile.vc DERIVATION
  records and the hermetic-environment finding (TCL<major>_<minor>_TM_PATH must
  be scrubbed alongside TCLLIBPATH/TCL_LIBRARY or a census measures the
  machine); no child AGENTS.md yet