# Achieved Goals Archive

This file holds summary records of goals that have been achieved and moved out of the active `GOALS.md` index to keep that file lean. Goals are archived as part of the achieved flip (see the `GOALS.md` maintenance rules). Records here are historical context only — they explain why code exists in its current shape and are useful when future agents refactor or revisit the same area.

## Format

Each archived goal is one compact record, preserving its original ID and acceptance criterion so it remains traceable:

```
### G-<id> [achieved <YYYY-MM-DD>] <short title> → detail: goals/archive/G-<id>-<slug>.md
Scope: <as in original index>
Acceptance: <as achieved>
```

The full record (including the Goal statement) lives in the archived detail file.

Do not edit archived entries except to fix a broken path. If an archived goal is reopened, move it back to `GOALS.md` with a new ID and mark the old entry `superseded by G-<new id>`.

(One sanctioned exception: the 2026-07-24 goals-system v2 delimiter normalisation rewrote archived Scope lines from comma to semicolon delimiters under explicit user approval; record content was otherwise unchanged.)

## Archived goals

### G-001 [achieved 2026-07-11] Pluggable console backends for non-detectable terminals → detail: goals/archive/G-001-pluggable-console-backends.md
Scope: src/modules/opunk/console-999999.0a1.0.tm; src/modules/punk/console-999999.0a1.0.tm; src/modules/punk/repl-999999.0a1.0.tm; src/lib/app-punkshell/punkshell.tcl
Acceptance: a subshell started with an ssh-channel-backed and a tk-widget-backed ::opunk::Console subclass runs an interactive REPL that reads/writes through that console; size, at_eof, and can_respond are answered by the subclass overrides; the base ::opunk::Console and punk::console module are unchanged.

### G-007 [achieved 2026-07-05] Location-transparent punk::console across repl and code interps → detail: goals/archive/G-007-console-location-transparency.md
Scope: src/modules/punk/console-999999.0a1.0.tm; src/modules/punk/repl-999999.0a1.0.tm; src/modules/punk/repl/codethread-999999.0a1.0.tm
Acceptance: from a running punk session's code interp, without `repl eval`: `console_fact_get` returns the same values the parent sees and a fact set in the parent is immediately visible; a terminal query (e.g. `get_cursor_pos` or `dec_get_mode`) against the default console succeeds and cooperates with the repl reader (no lost or garbled input); a console constructed and owned by code-interp code is operated on locally (no round-trip to the parent); the existing console test suites pass and single-interp (non-repl) usage is unchanged.

### G-015 [achieved 2026-07-07] Punk executable `script` subcommand: reliable non-interactive piped/script execution → detail: goals/archive/G-015-script-subcommand-piped-stdin.md
Scope: src/vfs/_config/punk_main.tcl; src/lib/app-punkshell/punkshell.tcl (script path or a leaner dedicated app package)
Acceptance: piping commands to `<punkexe> script` runs them and terminates at stdin EOF with no trailing `exit` required, exit code 0 on success; a failing piped command terminates the process with a nonzero exit code and the error on stderr, never landing in an interactive shell regardless of console availability or PUNK_PIPE_EOF; `<punkexe> script <file> [<args>...]` executes the file with conventional ::argv0/::argv and propagates its error status the same way; the script path installs none of the `shell` subcommand's shellfilter stacks/transforms and the launch plumbing itself emits nothing on stdout/stderr (the current stub's stderr diagnostics removed) so exec-style callers see only the script's own output; the motivating example works with no package require boilerplate: piping `dev projects.work *<name>*` to `<punkexe> script` emits the matching-project table and exits 0, because the script interp carries the default punk shell module/alias environment.

### G-036 [achieved 2026-07-08] Root-cause the Tcl 9 console+udp worker-thread event-loop wedge; minimal repro for possible upstream reporting → detail: goals/archive/G-036-tcl9-udp-console-worker-wedge.md
Scope: src/modules/shellthread-999999.0a1.0.tm; src/bootsupport/modules/shellthread-1.6.2.tm; src/modules/shellfilter-999999.0a1.0.tm (as characterised - no product-code changes required by this goal; the punkshell mitigations are separate fixes)
Acceptance: (reworked 2026-07-08 after the root cause was found) the wedge mechanism is identified and written up in the detail file - DONE: bundled tcludp 1.0.12's Windows per-thread UDP_ExitProc closes the process-global synchronization events, proven by dump handle-table analysis plus a live CloseHandle breakpoint and confirmed by the upstream 1.0.12->1.0.13 diff, which already fixes it (so no upstream report is required; the standalone minimal repro originally required here is waived as moot by the user); the tcl9 kits bundle tcludp >= 1.0.13 with the in-context batch harness baseline resolved - DONE 2026-07-08 (run-2 syslog workers alive vs the 4/4-wedged 1.0.12 baseline); DONE 2026-07-08 (punk::lib 0.3.0 has_libbug_udp_threadexit, surfaced via 'help tcl' in punk 0.2.1): a has_bug-style detection in the punkshell check machinery (in the vein of punk::lib::check::has_tclbug_* / punk::console::check::has_bug_*, surfaced through the same reporting as 'help tcl'/'help console') reports the vulnerable combination - simple version-based detection (loaded/bundled tcludp < 1.0.13 on Tcl 9 Windows) is sufficient, no behavioural probe needed; loose-end decisions (punk8win 8.6 kit's udp 1.0.12 swap; optional upstream tickets for residual tcludp trunk weaknesses) recorded in the detail file when made (open as of 2026-07-08 - non-gating).

### G-037 [achieved 2026-07-08] Propagate platform vendor libraries into kit vfs lib_tcl trees via make.tcl → detail: goals/archive/G-037-vendorlib-vfs-propagation.md
Scope: src/make.tcl (new or extended step); src/vendorlib_tcl8 + src/vendorlib_tcl9 (sources); src/vfs/<kit>.vfs/lib_tcl8 + lib_tcl9 (targets); punkcheck tracking
Acceptance: with a newer package version placed under src/vendorlib_tcl9/<platform>, one documented make.tcl invocation updates the participating src/vfs/*/lib_tcl9 trees - installing the new package and removing or explicitly retiring the superseded version (no silent mixed-version provision, per the G-035 concerns) - with punkcheck-tracked provenance; which vfs folders participate is explicitly declared per kit rather than blanket-copied (kit vfs package sets may intentionally differ), with the declaration mechanism recorded (candidate home: the G-024 mapvfs toml); a subsequent `make.tcl project` yields kits loading the new version (provable via the tcludp case: built punk902z reports `package require udp` == 1.0.13 with no udp1.0.12 folder remaining in its vfs); the lib_tcl8 tree gets the same treatment or an explicit exclusion rationale in the goal record.

### G-039 [achieved 2026-07-12] Investigate the orphaned-shell one-core spin on a dead console → detail: goals/archive/G-039-orphan-console-spin.md
Scope: src/modules/punk/repl-999999.0a1.0.tm (console reader/event loop and EOF/error paths); src/modules/punk/console-999999.0a1.0.tm; investigation-first
Acceptance: a documented procedure reproduces the spin on the current kit (e.g. launch an interactive shell in a terminal, then kill/close the hosting terminal or conhost), or the investigation records the attempts made and what evidence would reopen it; the spinning code path is identified (prime suspect: a console read/event loop treating a dead console's immediate EOF/error as retryable without backoff or termination - adjacent to the console-EOF restart path G-038 takes ownership of); after fix/mitigation, the same procedure shows the orphaned process exiting or settling at effectively zero CPU within a short grace period, with live-console interactive behaviour unchanged; the wedge-scoring hazard note (orphans polluting process-liveness checks in test harnesses) is updated to match the outcome.

### G-040 [achieved 2026-07-08] punk::args choice aliasing (-choicealiases) with parse normalization, display folding, and doc-lookup parity → detail: goals/archive/G-040-punkargs-choicealiases.md
Scope: src/modules/punk/args-999999.0a1.0.tm (parse + usage rendering); src/modules/punk/ns-999999.0a1.0.tm (cmdinfo/cmd_traverse choice resolution parity); src/modules/punk-999999.0a1.0.tm (punk::help topic argdoc as first consumer); src/tests/modules/punk/args/testsuites/; src/tests/modules/punk/ns/testsuites/
Acceptance: a definition using -choicealiases parses an alias (and an alias prefix where -choiceprefix allows) to its canonical choice in the parse result, with -choicerestricted 0 passthrough and the deny/reserve lists honoured unchanged; usage display shows one entry per canonical choice with aliases folded (no duplicate rows; -choicelabels attach to the canonical); punk::ns::cmdinfo/cmd_traverse resolve subcommand words to docids with the same outcome as the parser for alias, prefix, denied, reserved and unknown words (the pre-goal characterization tests updated from pinned-GAP to fixed); punk::help's topic definition adopts the feature so `i help` lists one entry per registered topic while `help h`/`help e` still fall through to command lookup; definitions without -choicealiases behave unchanged (existing punk::args and punk::ns suites pass).

### G-041 [achieved 2026-07-13] punk::args multi-form matching: automated form selection for parsing and documentation → detail: goals/archive/G-041-punkargs-form-matching.md
Scope: src/modules/punk/args-999999.0a1.0.tm (parse form selection, arg_error/usage form marking); src/modules/punk/ns-999999.0a1.0.tm (cmdhelp/synopsis closest-form indication); src/tests/modules/punk/args/testsuites/

### G-045 [achieved 2026-07-12] punk::args definition authoring ergonomics: record continuation, @cmd unindented fields, constructed-definition normalization → detail: goals/archive/G-045-punkargs-authoring-ergonomics.md
Scope: src/modules/punk/args-999999.0a1.0.tm (record parsing in resolve, tstr interplay, arg_error @cmd rendering); src/tests/modules/punk/args/testsuites/ (rendering.test/defquoting.test as the safety net); src/modules/punk-999999.0a1.0.tm (::punk::helptopic::define_docs de-hacked as the consumer proof)
Acceptance: a definition using the chosen record-continuation mechanism parses identically to its backslash-continuation equivalent (existing definitions unchanged - continuation is additive), with the token's collision rules documented and an escape/rejection story for values that legitimately match it; @cmd -help/-summary honour -unindentedfields (the rendering.test GAP rendering_unindentedfields_cmd_help_GAP flips to aligned); a constructed definition can request whole-block normalization so embedded continuation indentation behaves as in file-style definitions (the rendering_constructed_def_indent_characterization expectations updated to the chosen semantics), and ::punk::helptopic::define_docs drops its manual pre-normalization to prove it; the quoting rules from defquoting.test appear in the punk::args::define -help documentation; the full punk::args suite (128 tests incl. the rendering invariants: nesting independence, relative-indent preservation) passes with GAP tests flipped, none weakened.

### G-046 [achieved 2026-07-10] punk::args deferred -help resolution (parse-time performance + reentrancy) and rendering/value-shape fixes → detail: goals/archive/G-046-punkargs-deferred-help-and-fixes.md
Scope: src/modules/punk/args-999999.0a1.0.tm (resolve/get_dict: display-field deferral, dynamic-cache subst path, prefix writeback, string renderer, cmdhelp-facing messages); src/modules/punk/ansi-999999.0a1.0.tm (mark_columns argdoc as the reentrancy/perf testbed); src/tests/modules/punk/args/testsuites/ (GAP tests flip; perf verification)
Acceptance: parsing/argument resolution provably skips -help expansion (a definition whose -help contains a ${[...]} that would error or record its invocation shows the substitution did NOT run during a parse-only path, only for help display); first parse of punk::ansi::mark_columns drops from ~4s to well under a second with 'i punk::ansi::mark_columns' still rendering the embedded example, and a -help that parses its OWN definition id resolves or errors cleanly rather than looping; first-parse timing improves for at least one other heavily documented command (recorded in the detail file); rendering_atdynamic_multiline_help_insertion_GAP flips to all-aligned; choicegroups_imap_prefix_listwrap_GAP flips to shape-identical (prefix input yields the same plain string as exact input); the -return string renderer's cmd-help continuations align under the first line with relative indents preserved (rendering_string_renderer_characterization updated); the 'Bad number of leading values...' prefix shown by goodargs parsing in 'i string is'-style output is reworded or suppressed for the usage-display path; full punk::args and punk::ns suites pass with no non-GAP expectations weakened.

### G-049 [achieved 2026-07-10] punk::args parse-status data model with machine-parsable cmdhelp returns → detail: goals/archive/G-049-punkargs-parse-status-model.md
Scope: src/modules/punk/args-999999.0a1.0.tm (arg_error, parse error dispatch, colour-scheme handling); src/modules/punk/ns-999999.0a1.0.tm (cmdhelp); src/tests/modules/punk/args/testsuites/args/usagemarking.test; src/tests/modules/punk/ns/testsuites/ns/cmdhelp.test
Acceptance: cmdhelp -return dict distinguishes an incomplete, a fully-valid and an invalid argument set via per-argument statuses (received/ok/bad + overall scheme/message/form) with the structure documented; the table and string renderers derive their marking from that same structure, with rendered output unchanged except where the pinned GAP tests flip: badarg marking covers type/allocation failures not just choice violations (cmdhelp_GAP_no_badarg_marking_for_failed_typed_value), an explicit -scheme is honoured on the parse-failure path (cmdhelp_GAP_explicit_scheme_ignored_on_failure), the failure message names the queried command instead of cmdhelp's internal parse source line (cmdhelp_GAP_errormsg_leaks_internal_source), and scheme rendering no longer depends on or mutates shared colour state - the documented -scheme choice value 'nocolour' takes effect and repeated renders of the same call are identical regardless of prior scheme renders (usagemarking_GAP_scheme_nocolour_renders_with_leftover_colours, usagemarking_GAP_dash_nocolour_leaks_into_shared_array, usagemarking_GAP_dash_nocolour_leak_affects_later_info_render); all non-GAP characterization tests in usagemarking.test and cmdhelp.test pass unchanged.

### G-051 [achieved 2026-07-13] cmdinfo truthful cmdtype for doc-only pseudo-commands and space-form docid prefix parity → detail: goals/archive/G-051-cmdinfo-pseudo-and-prefix.md
Scope: src/modules/punk/ns-999999.0a1.0.tm (cmdinfo, cmd_traverse); src/tests/modules/punk/ns/testsuites/ns/cmdhelp.test; src/tests/modules/punk/ns/testsuites/ns/cmdflow.test
Acceptance: the pinned GAP tests flip: cmdhelp_GAP_pseudo_command_cmdtype_notfound and cmdhelp_GAP_string_is_true_pseudo report the new cmdtype with the docid unchanged, cmdhelp_GAP_spaceform_docid_prefix_not_honoured and cmdhelp_GAP_string_is_prefix_not_honoured resolve the child docid from a prefix exactly when parse accepts that prefix (honouring -choiceprefix, -choiceprefixdenylist, -choiceprefixreservelist and -choicealiases per G-040 parity); consumers of cmdinfo's cmdtype (cmdhelp, synopsis, eg) handle the new value with no behaviour change for real commands; cmdflow.test and the non-GAP cmdhelp.test tests pass unchanged.

### G-054 [achieved 2026-07-11] tclcore moduledoc: runtime-harvested 'string is' class choices with cross-version behavioural parity pins → detail: goals/archive/G-054-tclcore-stringis-harvest.md
Scope: src/modules/punk/args/moduledoc/tclcore-999999.0a1.0.tm (+ tclcore-buildversion.txt); src/tests/modules/punk/args/testsuites/args/ (new parity test); TEMP_REFERENCE/tcl9 (read-only reference)
Acceptance: parse/parse_status against ::tcl::string::is and its per-class virtual ids agrees with the real interpreter's error-vs-ok outcome for a pinned probe matrix (missing args, trailing flag-like str word, option/class unique-prefix acceptance and ambiguity rejection, unknown option/class, -failindex var consumption leaving no str, per-version class presence: dict, unicode) on Tcl 9.0.x and 8.6; the rendered choices show only classes the running interp accepts; the parity test derives expectations from the live interpreter (not version arithmetic) and passes under both; existing args/tclcore suites pass; tclcore buildversion bumped with changelog.

### G-058 [achieved 2026-07-10] Boot honours statically-linked runtime packages (static baseline seeding + packagepreference static-awareness) → detail: goals/archive/G-058-static-runtime-packages.md
Scope: src/vfs/_config/punk_main.tcl (boot auto_path/tm path filtering); src/modules/punk/packagepreference-999999.0a1.0.tm; src/modules/punk/repl-999999.0a1.0.tm + src/modules/punk/repl/codethread-999999.0a1.0.tm (code interp / codethread bootstrap); src/modules/shellthread-999999.0a1.0.tm (punkshell-created worker threads) as applicable; src/tests/ (un-gated unit tests + constraint-gated shell/kit integration tests); punkbin artifact repo (separate git repo, local checkout c:/repo/jn/punkbin - pinned runtime additions)
Acceptance: a punk91-style kit (tclsfe-x64 + punk9win.vfs, no thread dll in the vfs) boots to a working repl with no "can't find package Thread" - punk::console loads in the code interp, and package require Thread succeeds there and in a punkshell-created worker thread, resolving to the static version; in the same kit, twapi resolves per the documented policy (no repeat of the observed static-Twapi-masked-by-older-vfs-twapi-5.0.2 double load; a genuinely newer bundled copy remains reachable by that policy); dll-based kits (punk902z) boot and pass their existing shell test baseline unchanged, as does a plain tclsh dev launch; the seeding mechanism is generic - driven by the captured baseline, no runtime-specific package naming - and the boot-time static baseline is introspectable at the repl; the seeding/preference logic is covered by un-gated unit tests against simulated baselines (runnable under plain tclsh), while kit-boot integration tests are gated behind a capability-probed tcltest constraint (a built kit whose baseline shows static entries including Thread) that skips cleanly when no such kit is present; the runtimes used for verification (tclsfe-x64.exe at minimum) are added to the punkbin artifact repository under win32-x86_64 with sha1sums.txt updated, so the constraint is satisfiable on other machines via the existing runtime-retrieval path; the punk91 code-interp vfs/vfs::zip load failure is re-diagnosed after the fix and either resolved or recorded as a distinct issue/candidate goal.

### G-059 [achieved 2026-07-11] WSL detection and suitability probing for driving unix-side tests from Windows → detail: goals/archive/G-059-wsl-test-driving.md
Scope: src/tests/ (capability probe helpers + constraint-gated cases in existing suites, e.g the unix sh-payload execution test in modules/punk/mix/testsuites/scriptwrap/multishell.test and a runtime.bash behaviour test); src/tests/AGENTS.md (enablement notes)
Acceptance: a documented probe helper yields a wsl_linux_available constraint whose checks are capability-based (distro launches and answers uname/tool probes; staging into a native tempdir works) and which cannot misfire on wsl.exe-present-but-unusable installs (no distro, WSL1 limitations, broken interop); the currently unix-gated multishell sh-payload execution test runs green via WSL on a suitable machine and still skips cleanly elsewhere; at least one runtime.bash behaviour test (active/use/run resolution against a fixture runtime folder) runs inside WSL - all such tests executing from a native-filesystem staging dir with the shared path used only for one-way copy-in/out; the Windows checkout's git and fossil state is untouched by a WSL-gated run (verifiable: git status/fossil changes identical before and after); suite results on a WSL-less machine are unchanged (skips, not failures); enablement/limitations and the staging pattern recorded in src/tests/AGENTS.md.

### G-062 [achieved 2026-07-11] Canonical project license: BSD-2-Clause LICENSE file with SPDX-identified references → detail: goals/archive/G-062-project-license-file.md
Scope: LICENSE.txt (new, repo root); README.md; punkproject.toml ([project] license field); AGENTS.md (Repo-wide Notes license mention)
Acceptance: LICENSE.txt exists at the repo root containing the standard BSD-2-Clause text with a real copyright line; README.md names BSD-2-Clause and points at LICENSE.txt; root AGENTS.md Repo-wide Notes names the license precisely; punkproject.toml [project] carries license = "BSD-2-Clause"; a repo-sweep for top-level license claims finds none contradicting it (sweep result recorded here).

### G-071 [achieved 2026-07-12] punk::args value-allocation correctness for optional elements (lseq-class arglists) + parse_status -form → detail: goals/archive/G-071-punkargs-optional-allocation.md
Scope: src/modules/punk/args-999999.0a1.0.tm (get_dict value allocation, private::get_dict_can_assign_value, parse_status); src/tests/modules/punk/args/testsuites/args/ (new allocation characterization suite); src/modules/punk/args/moduledoc/tclcore-999999.0a1.0.tm (::lseq as the proving consumer)
Acceptance: a new allocation characterization suite drives the lseq range matrix under explicit -form range - '0 10', '0 10 2', '0 10 by 2', '0 to 10 2', '0 .. 10 by 2', '1 5 by 0' parse per the lseq.n grammar (the three currently-failing cases fixed) and '0 10 2 4' still fails - plus reduced fixtures isolating the shape (optional choice value between required values + trailing optional-member clause) independent of the moduledoc; the ::if noise-word cases (mid-clause ?literal(then)?, clause-leading ?literal(else)?) keep passing - no regression to optional clause members generally; a genuinely invalid arglist's error names the failing element (the '..|to' misblame case pinned fixed); punk::args::parse_status accepts -form (single form name/index at minimum, consistent with parse) with its status structure reporting the form used; full punk::args and punk::ns suites pass with no expectations weakened; before/after results for the probe matrix recorded in this file.

### G-030 [achieved 2026-07-14] make.tcl dogfoods punk::args: tabled usage, declared subcommands, prompt-free flags → detail: goals/archive/G-030-maketcl-punkargs.md
Scope: src/make.tcl (dispatch, help, prompts); src/bootsupport/AGENTS.md + src/modules/AGENTS.md (bootstrap-tracked staleness contract); src/modules/punk/args-999999.0a1.0.tm (only as consumed)
Acceptance: `tclsh src/make.tcl` and `-help` render punk::args tabled usage listing every subcommand with a summary, and `make.tcl help <subcommand>` (or `<subcommand> -help`) shows that subcommand's definition; invalid arguments produce a punk::args usage error rather than ad-hoc messages; every y/n prompt has a documented flag equivalent (proven at least for vfscommonupdate and the project-build confirmations: a run with the flag completes non-interactively with stdin closed) and a non-interactive stdin without the flag fails fast with usage rather than hanging or half-aborting; punk::args is added to the bootstrap-tracked buildversion set with the doc contract updated (src/bootsupport/AGENTS.md, src/modules/AGENTS.md); with bootsupport punk::args unavailable or unloadable, make.tcl still boots and `check`, `bootsupport` and `modules` remain usable with plain-text fallback help (the guarded-require degrade rule); layout make.tcl copies follow via the established sync/G-027 channels (noted, not hand-synced).

### G-074 [achieved 2026-07-13] punk::args multiform ambiguity analysis: on-demand form-overlap detection with sanctioned-overlap annotation → detail: goals/archive/G-074-punkargs-multiform-ambiguity-lint.md
Scope: src/modules/punk/args-999999.0a1.0.tm (analysis command, @form sanction key as decided in the work); src/modules/punk/args/moduledoc/tclcore-999999.0a1.0.tm (::after/::lseq as proving consumers, sanction adoption); src/tests/modules/punk/args/testsuites/args/ (new suite)
Acceptance: the analysis command reports the two known real cases from the G-041 closeout - ::lseq range/start_count overlap via the expr-typed end slot (unsanctioned finding: type-weakness class) and ::after cancelid/cancelscript (documented-overlap class) - and reports nothing for multiform definitions whose forms are fully discriminated (the parse withid/withdef pair, the forms.test afterish fixture); classifications distinguish at minimum type-weakness overlap (a discriminator aligned with a permissive type) from structural overlap (no discriminating slot exists); the sanction annotation silences (or downgrades to acknowledged) a listed form pair without affecting parse behaviour, is rejected at definition resolve when it names unknown forms, and is adopted for the after cancel pair in the tclcore moduledoc; the analysis is conservative in the documented direction (may miss deep ambiguities, must not false-alarm on discriminated forms - the miss/report boundary is documented with the slot model); running it performs no parse of user-supplied words and adds no work to define/resolve for definitions that never call it; a new testsuite covers the finding classes, the sanction, the unknown-form rejection and the no-finding cases; full punk::args suite passes.

### G-082 [achieved 2026-07-14] punk::args single-form parse error selection: specific validation failures preferred over generic overflow → detail: goals/archive/G-082-punkargs-error-selection.md
Scope: src/modules/punk/args-999999.0a1.0.tm (get_dict/parse error selection, validation-failure capture around the choice/type screens); src/tests/modules/punk/args/testsuites/args/ (characterization + regression suite)
Acceptance: a definition with an optional choice-restricted leader or value that receives a non-matching word reports a choiceviolation-class error naming the word and the allowed choices (message and -errorcode), not toomanyarguments - pinned for the make.tcl-style dispatch shape (optional subcommand leader with choices) and a values-position equivalent; a word rejected by a typed optional argument (e.g int) that then overflows reports the type failure similarly; genuinely-surplus cases (all optional args satisfied, extra word remains) still report toomanyarguments; multiform error selection (rank_form_failures) is unchanged or its pins deliberately updated; current 0.12.x behaviour is characterized first and the pins flipped deliberately; full punk::args suite passes with no expectations weakened; on completion the G-030 -optional 0 workaround sites are revisited (make.tcl dispatch definitions, the src/modules/AGENTS.md "punk::args definition authoring ergonomics" bullet) and relaxed or re-documented.

### G-091 [achieved 2026-07-19] runtests multiprocess parallelism (-jobs N) → detail: goals/archive/G-091-runtests-parallel-jobs.md
Scope: src/tests/runtests.tcl; src/tests/testsupport/; src/tests/AGENTS.md
Acceptance: -jobs 8 produces aggregate results identical to -jobs 1 (scriptlib/developer/runtests_parity.tcl reports PARITY ok) across repeated full-suite runs on a native tclsh 9.0.x, reduces full-suite wall time by at least 2.5x versus the sequential baseline on the reference machine, leaves the repo clean after runs (git status unchanged), and src/tests/AGENTS.md documents the -jobs flag and the serial-group policy.

### G-092 [achieved 2026-07-19] Split long-running test files to lower the parallel floor of broad runs → detail: goals/archive/G-092-split-longrunning-testfiles.md
Scope: src/tests/modules/punk/mix/testsuites/scriptwrap/ (multishell.test); src/tests/shell/testsuites/binscripts/ (dtplite.test); src/tests/modules/argparsingtest/testsuites/argparsingtest/ (argparsingtest.test); src/tests/shell/testsuites/punkexe/ (scriptexec.test - if assessed worthwhile); src/tests/runtests.tcl (longest-first weight table); src/tests/AGENTS.md + affected child AGENTS.md
Acceptance: after the split, repeated -jobs 8 full-suite runs on the reference machine report no child process wall above 45s in the runner's slowest-child listing and improve full-suite wall time by at least 25% versus the G-091 verification baseline (2m16s); test conservation is proven and recorded in this file - global tallies identical to a pre-split sequential baseline and the full set of test names unchanged (name-level comparison, mechanism decided in the work - e.g. a names mode for scriptlib/developer/runtests_parity.tcl); no test is deleted, skipped, weakened, or renamed, and provenance comment lines travel with moved tests; the runtests longest-first weight table covers the new files; scriptlib/developer/runtests_parity.tcl reports PARITY ok between -jobs 8 and -jobs 1 on the split tree; affected AGENTS.md contracts (src/tests + shell/binscripts and scriptwrap references) are updated.

### G-087 [achieved 2026-07-19] Thin project layouts: injected infrastructure, fauxlink layout refs, working overlay merge → detail: goals/archive/G-087-thin-project-layouts.md
Scope: src/project_layouts/ (payload store restructure); src/decktemplates/ (layout_refs migration to fauxlink); src/modules/punk/mix/commandset/project-999999.0a1.0.tm (project.new generation path); src/modules/punk/mix/commandset/layout-999999.0a1.0.tm; src/modules/punk/cap/handlers/templates-999999.0a1.0.tm (ref resolution); src/modules/punk/mix/#modpod-templates-999999.0a1.0/ (module-shipped refs/layouts); src/make.tcl (layout sync steps)
Acceptance: hygiene stage - in a punkshell checkout `dev project.new` with defaulted -layout resolves an exact layout name (no tcl::prefix ambiguity); the no-handler warning paths execute without error (put/puts typos fixed) and an absolute-pathtype provider registration does not raise an expr syntax error; test/junk refs (test2, sample-0.1 duplicate, the a.txt-only punk.shell-0.1) no longer present as selectable layouts; src/project_layouts/README.md describes the implemented punk.templates+refs mechanism including the ref filename grammar. Pivot stage - a project generated from the thin punk.project layout carries bootsupport modules matching the generating shell's current src/bootsupport (verified by comparing a marker module version such as punk::mix::cli, not a stored snapshot vintage); src/project_layouts contains no embedded bootsupport/vfs module trees and make.tcl's layout bootsupport-sync step is retired; layout refs are .fauxlink files resolved via the fauxlink module with the bespoke .ref parser removed, every layout ref carrying a non-empty nominal name (leading-# punkcheck-exclusion hazard documented in this file); a bare built kit run outside any project lists at least the module-shipped punk.project layout and generates a working project from it; and one overlay case exercising custom-over-vendor override, a .anti deletion, and a name@base derived layout (the existing sample-0.1/othersample fixtures) materializes correctly through the staging primitive into a generated project.

### G-093 [achieved 2026-07-20] runtests path-glob discovery: fix -include-paths multi-pattern/repeated-flag matching + expose -exclude-paths → detail: goals/archive/G-093-runtests-includepaths-discovery.md
Scope: src/tests/runtests.tcl; src/modules/punk/path-999999.0a1.0.tm (treefilenames/globmatchpath as implicated); src/modules/punk/args-999999.0a1.0.tm (only if -multiple implicated); src/tests/ (runner-targeting regression suite); src/tests/AGENTS.md
Acceptance: the G-092 four-subtree measurement set spelled X/*** discovers files from all four subtrees under the default *.test tail glob, and the X/** spelling of a base-direct suite matches zero files while emitting a stderr advisory (both pinned as characterization tests); two repeated -include-paths flags naming distinct subtrees in X/*** form discover both and equal the single-value form; the root cause of the original failures is identified and recorded in this file; punk::path 0.4.0 implements *** across pathglob_as_re/globmatchpath/treefilenames with the include and exclude lattice forms separable and pinned in the punk::path suite; -exclude-paths is exposed on runtests (argdoc + src/tests/AGENTS.md documented, accumulate semantics matching -include-paths, exclusion winning over inclusion for the same file) and a full run excluding a named subtree discovers exactly the default-discovery file list minus that subtree; -serial-paths classifies by the same directory-of-file reading; a regression suite under src/tests covers both options across single-value multi-pattern, repeated-flag, lattice-form and tail-glob-present/absent combinations plus include/exclude interaction; a full-suite default-discovery run before and after the changes compares PARITY ok via scriptlib/developer/runtests_parity.tcl (default '**' discovery with no exclusions must be unaffected); src/tests/AGENTS.md path-targeting wording is reconciled with the verified semantics.

### G-076 [achieved 2026-07-20] Adopt upstream tcl9 dead-console fix: shared version gate for watchdog and help tcl warning → detail: goals/archive/G-076-tcl9-deadconsole-fix-adoption.md
Scope: src/modules/punk/lib-999999.0a1.0.tm (punk::lib::check); src/modules/punk/repl-999999.0a1.0.tm (repl::start watchdog arming); src/modules/punk/AGENTS.md; src/tests/modules/punk/lib/testsuites/lib/checkbugs.test
Acceptance: 'help tcl' on an affected runtime shows the warning with the f10d91c2d3 link and mitigation note; the applicability decision is a pure facts-in/verdict-out classifier proc with tests (libbug_udp_threadexit_applies precedent); repl::start arms the watchdog only when the same classifier reports the runtime affected, with live-console/piped/8.6 behaviour unchanged; the fixed-in constant is set only after the G-039 kill procedure, re-run with the watchdog disabled on a runtime containing the upstream fix (an official release is not required - a runtime built from upstream sources at or past the fix merge qualifies), shows the repl exiting cleanly via the script-visible eof path - until then every Tcl 9 windows runtime is treated as affected.

### G-098 [achieved 2026-07-20] suite_tcl90 full punkshell dependency set: Tk+tklib, tcllib with critcl accelerators, and testsuite gating → detail: goals/archive/G-098-suite-tk-tcllib-critcl.md
Scope: src/buildsuites/suite_tcl90/ (recipe extensions, driver steps, testsuite gate); src/buildsuites/_build/ (tk/tklib/tcllib/critcl sources and outputs); bin/tools/ (pinned zig as consumed); src/tests/ (punkshell suites exercised against the suite-built runtime)
Acceptance: from the pinned zig and fetched sources the suite produces a Tk the suite tclsh loads (package require Tk with a create/destroy-window verification recorded in this file) and a matching tklib whose packages resolve from the install (a representative tklib package require recorded); a tcllib install performed via its own installer machinery (installer.tcl/sak.tcl behaviour checked and recorded - module selection, pkgIndex/tm generation, critcl module handling) whose accelerators load (package require tcllibc) with a punkcheck-relevant hashing comparison showing the accelerated path engaged versus pure-tcl; critcl is version-pinned and driven with zig cc; suite.tcl test gates on parsed totals against a recorded expected-failure baseline and the current 72 core-test failures are dispositioned (fixed or baselined with reasons); punkshell's runtests can run against the suite-built runtime with Tk-dependent suites no longer skipped for lack of Tk.

### G-096 [achieved 2026-07-20] Tracked zig tcl buildsuite (suite_tcl90) with recovered TCLSH_PIPEREPL kit-repl capability → detail: goals/archive/G-096-zig-buildsuite-piperepl.md
Scope: src/buildsuites/ (suite_tcl90 new; samplesuite1 sketch reconciliation; VCS ignore flip); src/buildsuites/_build/ (untracked build/source area via existing _build globs); .gitignore + .fossil-settings/ignore-glob; src/scriptapps/bin/ (getzig scriptset rename); bin/ (regenerated punk-getzig wrapper twins, old names retired, AGENTS.md naming policy); bin/tools/ (untracked zig toolchains, existing); TEMP_REFERENCE/2024zig (read-only recovery origin)
Acceptance: from a clean checkout plus a punk-getzig-fetched pinned zig, the suite builds tclsh90s/tclsh90szip from a fresh core-9-0-branch checkout under src/buildsuites/_build with recipe-generated tclUuid.h and tclsh.exe.manifest (no hand-placed files) and the result reports the expected patchlevel; the recovered patch set (piperepl plus the companion tclZipfs/tclCmdIL patches and a notes doc) is tracked in the suite; the rebased piperepl build gates per the G-103 punk-kit policy: with TCLSH_PIPEREPL=0 it behaves identically to the unpatched build on a tty/piped/script-arg matrix, with the gate open (unset or any other value - the default) scripts that never touch ::tclsh(dorepl) still behave stock on the same matrix (script-arg runs default dorepl to 0; unconsumed piped input is buffered in ::tclsh(inputbuffer), not eval'd), and a script setting ::tclsh(dorepl) 1 lands in a live interactive console repl after piped-input eof with the unconsumed input available in ::tclsh(inputbuffer); src/buildsuites is tracked in both VCSes with only _build content ignored and the samplesuite1 vendorbuild-prefix residue reconciled (vendorbuild concept retired); bin/AGENTS.md documents the utility naming policy (punk- prefix for punkshell-own utilities; exceptions: external-tool wrappers such as dtplite/sdx/kettle, and getpunk as the intended future cross-platform entry point) and the getzig scriptset and its bin wrapper twins (getzig.cmd/getzig.ps1) are renamed to punk-getzig with the old names removed and references updated.

### G-094 [achieved 2026-07-21] punkcheck single record lifecycle: OO installtrack as sole implementation with a persistence policy → detail: goals/archive/G-094-punkcheck-single-lifecycle.md
Scope: src/modules/punkcheck-999999.0a1.0.tm (installtrack/installevent lifecycle unification, installfile_* retirement, punkcheck::install as OO consumer); src/modules/punk/mix/cli-999999.0a1.0.tm + src/make.tcl (consumers verified unchanged); src/tests/modules/punkcheck/testsuites/punkcheck/ (characterization + new equivalence/staleness coverage)
Acceptance: characterization suites install.test and installtrack.test pass (pins flipped only where this goal's contract deliberately changes behaviour, each flip recorded); a new test pins field equivalence between batch-installed and OO-installed records (including -targets_cksums, which the legacy proc pipeline never stored); a new regression test covers o_record_list coherence - two sequential events on one installtrack instance, with targetset writes in the first event, lose nothing at the second start_event; grep of src/modules, src/make.tcl and src/project_layouts finds no live caller of the retired trio outside shims and tests; a full make.tcl build completes with skip/copy decisions unchanged against pre-refactor .punkcheck state (no spurious recopies of unchanged sources).

### G-095 [achieved 2026-07-21] punkcheck concurrent-writer safety: atomic saves and advisory event-scoped locking → detail: goals/archive/G-095-punkcheck-concurrent-writer-safety.md
Scope: src/modules/punkcheck-999999.0a1.0.tm (save/load chokepoint: atomic rename, lockfile protocol, merge-on-flush, non-interactive recovery); src/make.tcl + src/modules/punk/mix/cli-999999.0a1.0.tm (event-scoped lock consumers as verified); src/tests/modules/punkcheck/testsuites/punkcheck/ (new concurrency suite)
Acceptance: a concurrency test drives two child tclsh installer processes against one .punkcheck folder - the file parses cleanly throughout (a polling load_records_from_file reader hits no TDL parse error), both installers' records are present afterwards, and no duplicate INSTALLER records exist; lock behaviour verified - the second writer observably waits, or times out with a message naming the holder from lockfile contents; stale-break verified against a planted orphan lockfile; suite passes on the project's Windows Tcl 8.6 + Tcl 9 test matrix (capability-gated where child-process facilities require it), with a unix run when an environment is available.

### G-102 [achieved 2026-07-21] buildsuite bootstrap without a pre-existing tclsh: zig-driver hybrid → detail: goals/archive/G-102-buildsuite-zig-bootstrap.md
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)
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).

### G-097 [achieved 2026-07-21] bin utility naming sweep: punk- prefix for remaining punkshell-own tools → detail: goals/archive/G-097-bin-utility-naming-sweep.md
Scope: src/scriptapps/ + src/scriptapps/bin/ (bits, runtime, tclargs scriptset renames; selfsign experiment scripts); bin/ (regenerated wrapper twins + renamed experiment scripts, old names retired); src/tests/modules/punk/mix/testsuites/scriptwrap/ + src/tests/shell/testsuites/binscripts/ (roundtrip pins); bin/AGENTS.md + referencing docs; src/project_layouts/vendor/punk/project-0.1/bin + the modpod-templates layout equivalent (layout-shipped utility copies - folded in by user 2026-07-21)
Acceptance: bin/ presents punk-bits, punk-runtime and punk-tclargs (wrapper twins where the polyglot system emits them) and punk- prefixed selfsign experiment scripts, with the old names removed; scriptset sources and _wrap.toml configs are renamed to match; the byte-roundtrip pins (scriptwrap multishell runtime roundtrip, binscripts suites as affected) and every doc/script reference to the old names are updated with the affected test suites passing; no behaviour changes ride along with the renames.

### G-107 [achieved 2026-07-21] Buildsuite library test runs: record/gate external library testsuites → detail: goals/archive/G-107-buildsuite-library-tests.md
Scope: src/buildsuites/suite_tcl90/ (per-library test steps in recipe, tools/ runners, tracked dispositioned baselines); src/buildsuites/_build/ (report outputs via existing globs); pattern inherited by later suites (suite_tcl86)
Acceptance: thread and tclvfs run gated with tracked dispositioned baselines, deterministic across two consecutive full runs; tcllib (with tcllibc accelerators engaged) and tklib run in record mode emitting report artifacts whose paths are recorded in this file; a Tk step exists opt-in with a recorded first census; per-library policy is overridable at invocation without recipe edits; a testsuite that fails to complete (no totals) fails its step in every mode; the evidence-summary shape G-103 metadata consumes is documented here.

### G-106 [achieved 2026-07-22] powershell console-mode fallback: maintained raw-mode path for twapi-less runtimes → detail: goals/archive/G-106-powershell-consolemode-fallback.md
Scope: src/modules/punk/console-999999.0a1.0.tm (enableRaw_powershell/disableRaw_powershell + the persistent server lifecycle); scriptlib/utils/pwsh/ (consolemode_server_async.ps1 canonical + experiment-variant reconciliation); ps-script resolution/packaging across launch contexts (argv0-derived pstooldir; kits via the G-089 scriptlib-in-kits interplay); src/make.tcl shell (the verified launch context)
Acceptance: on a twapi-less suite runtime, raw enable/disable work via the fallback from (a) the make.tcl shell launch and (b) a kit / plain-tclsh repl launch, with no stderr noise in normal operation; the server lifecycle is verified - starts once per session, stays up for the session's raw transitions (the 2026-07-20 observed early-shutdown mode diagnosed and fixed), and shuts down with the session leaving no orphan pwsh processes; ps-script resolution no longer depends solely on argv0 parent-dir derivation (works from kits and unusual cwds, with the fallback-to-pwd branch replaced by something principled); scriptlib/utils/pwsh is reconciled to one canonical server script with the experiment variants retired or explicitly labelled; the fallback's role as the no-twapi contingency is documented where G-103's twapi investigation will find it, and a repeatable verification recipe is recorded in this file.

### G-103 [achieved 2026-07-22] runtime kit family from buildsuites: plain / punk / bi kits with attached batteries + artifact metadata → detail: goals/archive/G-103-runtime-kit-family.md
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 (punk-runtime list/use - renamed under G-097, achieved 2026-07-21)
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, with piperepl-patched runtime executables carrying 'punk' in the name to distinguish them from unpatched (e.g tclsh905punk.exe - the tcl-patchlevel / punk-version / separator questions resolved and the decision recorded here) and mapvfs.config consuming the punk/bi runtimes under the decided names; the 8.6 family variant is explicitly deferred to the G-101 container investigation (static vfs / metakit patching questions).

### G-117 [achieved 2026-07-24] Self-describing family runtimes: embedded artifact record + metadata schema v1 → detail: goals/archive/G-117-self-describing-runtimes.md
Scope: src/buildsuites/suite_tcl90/ (kit-family staging embeds the record; family_artifacts.tcl schema v1 fields + emission ordering; -Doriginurl/-Dpackager options); tools/family_check.tcl (embedded-record verification); src/scriptapps/bin/punk-runtime.* + bin/punk-runtime.cmd via rewrap ('info' action; schema-tolerant parsing); punkbin AGENTS.md (record relationship + schema/field documentation)
Acceptance: kit-family embeds the record in all three members with the embed-then-hash ordering documented; family_check verifies the embedded record exists and matches probed facts; 'punk-runtime info' identifies fetched-with-sidecar and bare-renamed copies via a non-executing zip central-directory read (cooperative probe documented as fallback) and flags embedded-vs-sidecar disagreement; v1 fields documented in punkbin AGENTS.md; build_id identical embedded+sidecar; '#' field comments emitted; parsing tolerates unknown fields/absent schema (pre-v1 r1 keeps working); both payloads in parity with the roundtrip pin green; r2 re-emitted carrying the full v1 record (r1 immutable as published).

### G-118 [achieved 2026-07-25] tclsh subcommand review: stock-parity gaps, piperepl residue, docs and console-path tests → detail: goals/archive/G-118-tclsh-subcommand-review.md
Scope: src/vfs/_config/punk_main.tcl (tclsh dispatch); src/vfs/_config/project_main.tcl (parity); src/buildsuites/suite_tcl90/patches/ (tclMain piperepl rev items); src/tests/shell/testsuites/punkexe/tclshcmd.test (coverage additions)
Acceptance: Every item in the "Issue list" section carries a recorded user decision (fix / document-as-intended / wontfix) and the decided fixes and documentation have landed; the tclsh subcommand's user-facing contract is documented in a durable doc location (not TEMP_REFERENCE); tclshcmd.test covers the decided pipe-testable behaviours; and the dorepl/console-reopen path either has a console-driven test or a recorded decision that G-106-style coverage is not required.

### G-119 [achieved 2026-07-25] punk-runtime active-vs-default freshness verdict (ahead/behind/current) → detail: goals/archive/G-119-runtime-active-freshness.md
Scope: src/scriptapps/bin/punk-runtime.ps1 + punk-runtime.bash (+ rewrapped bin/punk-runtime.cmd); bin/AGENTS.md (runtime-manager contract); src/tests/modules/punk/mix/testsuites/scriptwrap/ (roundtrip pin; behavioural fixture surface settled in the work)
Acceptance: against a fixture punkbin server (PUNKBIN_URL override): list -remote prints explicit ahead/behind verdicts naming both revisions (behind adds fetch+use update guidance) and keeps the (= server default) annotation for current; a pre-family active (no toml, no -rN name) yields a stated no-revision-basis note or its sha1 hash-identity when it value-matches a server artifact; a no-name fetch prints a one-line active-vs-default note on divergence; both payloads deliver identical verdict lines (fixture surface settled: shell/testsuites/binscripts/runtimecmd_freshness.test + testsupport/httpfixture.tcl); the runtimecmd roundtrip pin stays green; bin/AGENTS.md's runtime-manager contract records the new surface.

### G-120 [achieved 2026-07-25] 9.1-kit script-mode boot pins process std channels: find holder, restore std-slot recycling → detail: goals/archive/G-120-scriptmode-std-channel-pin.md
Scope: src/modules/punk/console-999999.0a1.0.tm; src/modules/punk/repl-999999.0a1.0.tm; src/lib/app-punkscript/; src/vfs/_config/punk_main.tcl
Acceptance: the registration holder is named (module, proc, mechanism) with reproduction evidence; the disposition is recorded here (deliberate-and-documented, or fixed); a script-mode run of the recipe `chan close stderr; open NUL w` on the current 9.1 kit yields a channel auto-named stderr with working puts stderr, and the console + repl module suites (src/tests/modules/punk/console/, src/tests/modules/punk/repl/) pass.

### G-113 [achieved 2026-07-25] make.tcl colour output is terminal-aware: SGR only on interactive tty, off when piped → detail: goals/archive/G-113-maketcl-tty-aware-colour.md
Scope: src/make.tcl (startup colour policy, define_global_ansi); src/AGENTS.md (invocation guidance); src/tests/shell/testsuites/punkexe/ (piped-output characterization if a suite proves feasible); layout make.tcl copies via established sync channels
Acceptance: With NO_COLOR unset, representative informational and build subcommands (at minimum check, help, workflow, and one build command such as modules) run with stdout redirected to a file produce zero ESC (0x1B) bytes on stdout and stderr, verified on tclsh 9.x and a repo punk kit. The same commands on a real interactive terminal retain colour (manual verification, Windows console plus one unix tty). NO_COLOR=1 still suppresses all colour; a documented force-colour override re-enables colour on piped output. The Tcl 8.6 probe-fallback policy is documented and behaves as decided. The interim src/AGENTS.md NO_COLOR bullet is revised to describe the implemented behaviour.

### G-112 [achieved 2026-07-25] make.tcl subcommand rename: stage-true vocabulary around the promotion gates → detail: goals/archive/G-112-maketcl-subcommand-rename.md
Scope: src/make.tcl (subcommand tables, dispatch gating, help/workflow text); src/project_layouts/vendor/punk/basic/src/make.tcl + src/project_layouts/vendor/punk/project-0.1/src/make.tcl + src/modules/punk/mix/#modpod-templates-999999.0a1.0/templates/project_layouts/vendor/punk/project-0.1/src/make.tcl (layout copies via established sync channels); AGENTS.md + src/AGENTS.md + src/modules/AGENTS.md + src/lib/AGENTS.md + src/vfs/AGENTS.md + src/tests/AGENTS.md + src/tests/shell/AGENTS.md + README.md + src/README.md (workflow references); src/tests/shell/testsuites/punkexe/scriptexec.test + src/tests/shell/testsuites/punkexe/staticruntime.test (as touched)
Acceptance: (1) `make.tcl bake` on a clean checkout produces kits byte-comparable to what `make.tcl vfs` produced at the same tree (allowing only known-nondeterministic zip metadata), and additionally runs the vfslibs phase so a bake cannot ship stale binary libs; (2) `make.tcl project` and `make.tcl vfs` still work as deprecated aliases that print a one-line deprecation notice naming their replacement; (3) `make.tcl bakehouse` defaults `-dirty-abort` on and its abort message names the granular developer flow; (4) `make.tcl help`/`workflow` output and every doc in Scope describe the two-persona flow (consumer: `bakehouse`; developer: packages -> test -> bootsupport/vfscommonupdate -> commit -> bake) with no remaining instruction to run bare `make.tcl project` as the recommended path; (5) the punkexe testsuites pass against a kit built with the new names.

### G-104 [achieved 2026-07-25] make.tcl buildsuite surface: list / info / build → detail: goals/archive/G-104-maketcl-buildsuite-surface.md
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)
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.

### G-121 [achieved 2026-07-26] make.tcl bakelist + selective bake: list configured kits, bake by name → detail: goals/archive/G-121-bakelist-selective-bake.md
Scope: src/make.tcl (bake @values + new bakelist subcommand; SUBOPTS/SUMMARIES/HELPTEXTS/SUBGROUPS, help/workflow text); src/runtime/mapvfs.config (as read; todo-comment retirement); src/tests/shell/testsuites/punkexe/ (bakelist characterization if feasible); layout make.tcl copies via established sync channels
Acceptance: `make.tcl bakelist` under a plain tclsh and under a punk kit executable lists every kit output configured in the runtime mapping with name, kit type, runtime (present/missing), vfs folder and a deployed-state indication (bin copy absent/current/stale vs the build product), and `bakelist <kitname>` filters to the named entries; `make.tcl bake <kitname ...>` builds and deploys only the named kit(s) - a recorded verification shows the named kit's artifacts refreshing while other kits' _build/bin artifacts and punkcheck records are untouched - and an unknown name errors without building, listing the configured names; bare `make.tcl bake` processes the same kit set as before the change; help/workflow text documents both per the update contract and the mapvfs.config todo comment is retired to point here; a piped bakelist characterization test lands under punkexe if feasible (else the infeasibility is recorded here); project version minor-bumped with a CHANGELOG entry.

### G-099 [achieved 2026-07-26] suite_tcl86: zig buildsuite for core-8-6-branch (runtime, thread, tclvfs, core-test gate) → detail: goals/archive/G-099-suite-tcl86-buildsuite.md
Scope: src/buildsuites/suite_tcl86/ (new: suite.tcl driver, 8.6 zig recipe + helper modules, expected_test_failures baseline); src/buildsuites/_build/ (untracked sources/outputs via existing globs); bin/tools/ (pinned zig as consumed); PUNK_FOSSIL_STORE / ~/.punkshell/fossils (hermetic clone store shared with suite_tcl90)
Acceptance: from the pinned zig and fetched core-8-6-branch sources (hermetic clone store, no MS toolchain) the suite produces a working tclsh86 executable and tcl86 dll with an installed lib tree the shell resolves without external Tcl installations (TCLLIBPATH/TCL_LIBRARY unset in all suite child invocations); an 8.6-compatible thread package and tclvfs build and load in that shell (versions recorded); suite.tcl test runs the 8.6 core testsuite, parses totals (exit codes not trusted), and gates against a tracked expected_test_failures baseline with every entry dispositioned with a reason - a full-run PASS deterministic across two consecutive runs is recorded in this file; an interactive-smoke record (script execution, package require checks) is captured here.

### G-100 [achieved 2026-07-26] suite_tcl86 dependency set: Tk 8.6 + tklib, tcllib with critcl accelerators, punkshell runtests on the 8.6 runtime → detail: goals/archive/G-100-suite-tcl86-tk-tcllib.md
Scope: src/buildsuites/suite_tcl86/ (recipe extensions, driver steps); src/buildsuites/_build/ (tk/tklib/tcllib/critcl sources and outputs); bin/tools/ (pinned zig as consumed); src/tests/ (punkshell suites exercised against the suite-built 8.6 runtime)
Acceptance: from the pinned zig and fetched sources the suite produces a Tk 8.6 the suite tclsh loads (package require Tk with a create/destroy-window verification recorded here) and a matching tklib whose packages resolve (a representative require recorded); a tcllib install via its installer whose accelerators load (package require tcllibc) with the accelerated-vs-pure comparison recorded; punkshell runtests runs against the suite 8.6 runtime and its census is recorded here against a same-day native/kit 8.6 baseline run (same include set), with every difference dispositioned - Tk-dependent suites run unskipped, and any 8.6-runtime-only failures are root-caused or baselined with reasons.

### G-122 [achieved 2026-07-26] make.tcl host/target platform split: bake by target, not host personality → detail: goals/archive/G-122-host-target-platform-split.md
Scope: src/make.tcl (target-platform derivation; store folder, exe suffixing, kit naming, presence checks and process-sweep tooling keyed by target; platform-canon inline copy; zipfs-less zip-type assembly fallback); src/modules/punk/platform-999999.0a1.0.tm (stable canon tags for cygwin-family hosts, help platforms doc); src/runtime/mapvfs.config (per-entry target platform via minimal compatible extension - format ownership coordinated with G-024); bin/runtime/<platform>/ store tiers (as consumed; fixture tier for tests); src/tests/shell/testsuites/punkexe/ (characterization)
Acceptance: an msys/cygwin-runtime tclsh driving bakelist/bake on windows reports - and for a changed kit, bakes and deploys - the same win32-x86_64 kit set with identical names and store addressing as a native tclsh, with the pre-deploy process sweep using windows tooling for win32 targets regardless of host personality; punk::platform and the make.tcl inline canon map MSYS_NT/MINGW64_NT/CYGWIN_NT/UCRT64-class hosts to stable documented tags (MSYSTEM-variance documented, no windows build number in the tag) and 'help platforms' lists them; a mapvfs entry declaring a non-default target platform lists in bakelist with its own tier's store presence and bakes to a correctly suffixed artifact, verified against a fixture store tier (a real third-party runtime is not required); a zipfs-less driving tcl (8.6) assembles a zip-type kit via runtime split + punk::zip::mkzip + concatenation (archive-start-relative offsets) and the artifact boots on a zipfs-capable runtime; the linuxulator expectation (a linux-personality tclsh on FreeBSD 14/15 addresses the linux-x86_64 store unchanged) is recorded here with verification deferred to the planned linux-kit-on-FreeBSD trial; native-windows behaviour stays characterization-stable (existing punkexe maketcl tests pass unchanged).

### G-124 [achieved 2026-07-26] Dependency-free zip reading in punk::zip: archives, runtime-prefixed executables, and a scripter-facing introspection surface → detail: goals/archive/G-124-punkzip-reader.md
Scope: src/modules/punk/zip-999999.0a1.0.tm (reader + introspection procs, base-offset derivation factored out of extract_preamble for shared use, buildversion); src/make.tcl (zipfs-less kit extraction path as first consumer - the zipfile::decode requirement is removed, not made optional); src/tests/modules/punk/zip/ (new testsuite - mkzip round-trip, prefixed-archive cases, introspection, unsupported-input behaviour); bootsupport + src/vfs/_vfscommon.vfs copies via established sync channels
Acceptance: punk::zip extracts to a target directory from (a) a plain zip, (b) an executable-prefixed archive with archive-relative offsets and (c) one with file-relative offsets - bin/runtime/win32-x86_64/tclsh90b4_piperepl.exe is the recorded (c) case, on which the current split-then-tcllib path fails with "Bad zip file. Bad closure." - producing CRC-verified byte-identical members with directory entries materialized as directories, on a tclsh with no zipfs, no vfs::zip and no tcllib reachable (the interpreter used is recorded here); an introspection call lists members without extracting, returning per-entry name, size, compressed size, method, mtime, crc and directory-vs-file, over the same three input shapes, and both surfaces carry punk::args definitions with worked examples so 'i punk::zip::<proc>' documents them; unsupported inputs (zip64, encrypted, unknown compression method) fail naming the reason rather than emitting partial or garbled output; make.tcl's zipfs-less kit extraction consumes the new surface and NO zipfile::decode requirement remains anywhere in the shipped tree, verified by a tree grep, and demonstrated by an 8.6 zipfs-less bake of a zip kit on a tcllib-less tclsh (msys2 /usr/bin/tclsh8.6 as reference host) producing an artifact that boots with its tcl_library present; a new src/tests/modules/punk/zip/ suite covers a mkzip -> read round trip asserting names, content, directory-vs-file classification and stored attributes - recording the answer to the standing zipfs dir-misidentification question noted in punk::mix::cli and src/vfs/mkzipfix.vfs - plus the three prefixed-archive cases, the introspection output, and the unsupported-input failures; punk::zip buildversion minor-bumped with its changelog line.