G-169/G-170 follow-on landed: coherent-set promotion + bake - launcher help depth reaches the kits (punkshell 0.56.0)
Both goals' open coherent-set promotion follow-ons name the SAME
vfscommonupdate/bake event; this change-set is that event, so both flip to
landed 2026-08-06 in the same work unit (the sanctioned archived-file edit).
Promotion (canonical release-sequence steps 5-8, native tclsh90 driver):
- mint: 'make.tcl packages -confirm 0'.
- promote: 'make.tcl bootsupport -confirm 0' - punk::args 0.17.0 -> 0.18.0 and
punk::ansi 0.1.3 -> 0.2.0. The second pass copied zero modules (the gate's
own contract) and 'make.tcl check' no longer reports stale bootsupport.
- promote: 'make.tcl vfscommonupdate -confirm 0' - the same two modules plus
punkboot core 0.7.0 (byte-identical to src/vfs/_config/punkboot_core.tcl),
punkexe moduledoc 0.6.1 -> 0.9.0, punkboot moduledoc 0.3.0 -> 0.3.1, and
app-punkscript/app-punkscript-docs 1.1 -> 1.3 (pkgIndex + punkscript.tcl;
vfscommon never carried the intermediate 1.2). Every promoted copy verified
byte-identical to its mint output.
- bake: 'make.tcl bake -confirm 0' - INSTALLED KITS (11), no FAILED KITS. The
templates modpod payload (both bootsupport and vfscommon copies) regenerated
from the G-170 layout core edits.
What a deployed kit now does that it could not before, probed directly against
bin/punk902z.exe (no src package mode, no fake-main harness):
- 'help script oneliner' narrows to the oneliner form's argument table - the
'-e' row, which is absent from form 0's default table - exit 0.
- the multi-form synopsis lines carry the un-suppressed formhint labels
(' <punkexe> help script file' / ' <punkexe> help script oneliner'), G-170's
resolution of the 0.6.1 circularity objection, rendered from the app-owned
definition G-169 moved beside the code that implements it.
- 'help script somefile.tcl' dry-runs: the matched form plus the
punk::args::parse_report landing report (Argument|Source|Value carrying
'scriptfile received somefile.tcl') - G-151's render consumed by the core.
- 'help buildinfo bogus' rejects with exit 1, byte-empty stdout and the parse
diagnosis on stderr; 'help shell somearg' keeps the passthrough
accepted-and-ignored render at exit 0.
- 'help tclsh somefile somearg' now DRY-RUNS (accepted, exit 0) where the baked
0.6.1 moduledoc had kept the historic ignored-tail render: the G-170 fence
witness requires a -regexprefail row in the definition actually served, and
the promoted 0.9.0 moduledoc supplies it. That was the recorded
mixed-vintage state, now resolved in the deployed kits.
Verification:
- launcherhelp.test 38/38 against the freshly baked kits. The two direct-kit
trailing-word pins that G-170 re-described as VINTAGE-PROOF hold under the
depth core exactly as designed.
- Full source-tree suite (-jobs 16): 1560 passed / 20 skipped / 1 failed. The
single failure is core/tcl/testsuites/tests/exec.test exec-14.3, a vendored
Tcl core test asserting stock's 'exec -gorp' error text without -encoding -
a Tcl 9.0.3 core-vintage mismatch, unrelated to this change-set.
- punkexe subtree 162 passed / 4 skipped / 0 failed. The 10 failures recorded
as pre-existing through the G-168/G-169/G-170 sessions (maketclbakelist 2 +
maketcllibfetch 8) now ALL PASS - they were stale build-state artifacts, and
this mint/promote/bake refresh is precisely what they were waiting for. Worth
weighing against the G-139 libfetch-test reading still pending a user call.
- punk/args subtree 337 passed / 3 skipped / 0 failed, its recorded baseline.
- Bake warnings are the known set only: punkmagic skipped (runtime
tclsh90magic.exe absent from the store) and the zint.dll i386-in-x64 arch
mismatch in the tcl8 kits punkbi/punksys/punk86, the recorded pre-existing
payload defect. No configured kit exe was locked (the running punk901t.exe
instances are not a configured bake target).
Project version 0.55.1 -> 0.56.0 with a CHANGELOG entry: the G-151/G-168/G-169/
G-170 launcher-family behaviour becomes user-visible in a deployed kit for the
first time with this bake, and none of those source commits bumped the project
version - the source change alone shipped nothing to a user.
ARCHITECTURE.md's launch-surface paragraph still described trailing help words
as merely 'accepted', which is pre-G-170 semantics, so that clause now states
the narrowing / dry-run / passthrough split; architecture_lint clean (66 path
refs, 62 goal refs). goals_lint clean (80 active / 90 archived).
Deliberately untouched and still open: G-151's make.tcl interim-report
retirement (its bootsupport gate is satisfied by this promotion, but the
make.tcl edit is separate work), G-169's app-ownership extension to
shell/punk/shellspy, and G-170's punkboot moduledoc authoring-hint note.
Claude-Session: https://claude.ai/code/session_01Y1diJnhjUxKgEG6EwYAzxj
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
- **Kit anatomy.** Each `src/vfs/*.vfs` folder is a runtime payload; `src/runtime/mapvfs.toml` (G-024, tomlish-parsed; deprecated `mapvfs.config` line format still readable) maps payload folders to platform runtimes under `bin/runtime/<platform>/` as named kit outputs, with named groups and generative version-named schemes; an optional sibling `src/vfs/<name>.vfs.toml` declares payload packages materialized INTO the folder with drop-in-wins precedence (G-115 - spec: `src/vfs/README.md`); `src/vfs/_vfscommon.vfs/` is a generated merge of common libraries (never hand-edited); `src/vfs/_config/` holds the entry scripts. Sources: `src/vfs/AGENTS.md`, `src/runtime/AGENTS.md`.
- **Entry point.**`src/vfs/_config/punk_main.tcl` (thin main sourcing the shared boot core - G-031). An optional first argument is a dash-delimited package mode composed of tokens from `minted`, `os`, `src`, `internal` (`internal` is always appended when absent; `minted` was named `dev` pre-0.43.0), optionally scoped with the `proj:` prefix (G-033: `minted`/`src` resolve against the project containing the cwd - walk-up to the nearest git/fossil repo root with a punkshell-style src tree - instead of the executable's own project; discovery is always reported, never a silent rebind). The next argument is the subcommand: `shell`, `script`, `punk`, `tclsh`, `shellspy`, `buildinfo`, `help`. A non-subcommand first argument naming an existing file (or `lib:*` reference) is treated as a script invocation; a first argument of exactly `-e` runs the following argument as a Tcl one-liner (G-077, achieved - handled as `script -e`; tool-style kits keep `-e` routed to their own processor); anything else is refused with usage (G-032); no arguments at all means interactive shell. Subcommands map to app packages under `src/lib/` (`app-punkshell`, `app-punkscript`, `app-repl`, `app-shellspy`). The launch surface self-documents through punk::args (G-032; single-mechanism revision 2026-08-05 in boot core 0.5.0): `help ?subcommand? ?arg ...?` - the only help entry, trailing words accepted so `help` can be prepended to a command line - renders tabular usage from the moduledoc definitions plus project registrations (`::punkboot::project_subcommand_info` - summaries, definition ids, optional declared parse), degrading to a plain subcommand list when that stack is unavailable; help FLAGS are never intercepted (a leading `-help` earns the refusal, `<subcommand> -help` belongs to the subcommand). Source: `src/vfs/AGENTS.md`.
- **Entry point.**`src/vfs/_config/punk_main.tcl` (thin main sourcing the shared boot core - G-031). An optional first argument is a dash-delimited package mode composed of tokens from `minted`, `os`, `src`, `internal` (`internal` is always appended when absent; `minted` was named `dev` pre-0.43.0), optionally scoped with the `proj:` prefix (G-033: `minted`/`src` resolve against the project containing the cwd - walk-up to the nearest git/fossil repo root with a punkshell-style src tree - instead of the executable's own project; discovery is always reported, never a silent rebind). The next argument is the subcommand: `shell`, `script`, `punk`, `tclsh`, `shellspy`, `buildinfo`, `help`. A non-subcommand first argument naming an existing file (or `lib:*` reference) is treated as a script invocation; a first argument of exactly `-e` runs the following argument as a Tcl one-liner (G-077, achieved - handled as `script -e`; tool-style kits keep `-e` routed to their own processor); anything else is refused with usage (G-032); no arguments at all means interactive shell. Subcommands map to app packages under `src/lib/` (`app-punkshell`, `app-punkscript`, `app-repl`, `app-shellspy`). The launch surface self-documents through punk::args (G-032; single-mechanism revision 2026-08-05 in boot core 0.5.0): `help ?subcommand? ?arg ...?` - the only help entry, trailing words accepted so `help` can be prepended to a command line, with depth since G-170 (boot core 0.7.0): a single word naming one of a multi-form definition's forms (or a decimal ordinal) narrows the render to that form's argument table, any other tail on a parse-true subcommand is dry-run through its definition (accepted lines add the `punk::args::parse_report` landing report, rejected lines emit the parse diagnosis on stderr with exit 1), and passthrough subcommands keep the ignored tail - renders tabular usage from the moduledoc definitions plus project registrations (`::punkboot::project_subcommand_info` - summaries, definition ids, optional declared parse), degrading to a plain subcommand list when that stack is unavailable; help FLAGS are never intercepted (a leading `-help` earns the refusal, `<subcommand> -help` belongs to the subcommand). Source: `src/vfs/AGENTS.md`.
- **Package modes pick module provenance.**`internal` uses module snapshots baked into the kit at bake time; `minted` loads the mint output trees at repo-root `modules/` and `lib/`; `src` loads the unbuilt working tree (`src/modules`, `src/lib`, `src/bootsupport`, `src/vendormodules`) with `package prefer latest` so magic-version dev modules (`999999.0a1.0`) beat stamped snapshots. `src` mode is the standard way to verify working-tree changes without a rebuild. Source: `bin/AGENTS.md` "Launch package modes".
- **Payload mount derivation (G-129, achieved).** The boot keys zipfs presence on `tcl::zipfs::mount` and derives where the executable's attached archive actually mounted from the mount table itself (the entry whose archive file is the executable; fallback: the mount containing the boot script) instead of assuming `tcl::zipfs::root` + `//zipfs:/app`. Modern runtimes still answer `//zipfs:/app`; the androwish/undroidwish 8.6 backport has no `root` command, mounts at the executable's own path, and boots the same payload through its `app/main.tcl` in-archive hook (`src/vfs/punk8win.vfs` carries fauxlinks for both conventions). A mounted archive the boot cannot attribute is reported on stderr rather than silently yielding no internal paths. The derivation procs stay defined post-boot (`::punkboot::zipfs_kit_mountbase`). Sources: `src/vfs/AGENTS.md`, `bin/AGENTS.md` "Kit-wrappable runtime requirements", `src/tests/shell/testsuites/punkexe/kitmountpoint.test`.
- **Static package capture (G-058, achieved).** Boot probe-loads the runtime's statically linked packages in a throwaway interp and records what each provides; every interp the shell fabricates (boot, codethread, shellthread workers) seeds `package ifneeded <name> <ver> {load {} <prefix>}` from that record, and `punk::packagepreference` resolves static-vs-bundled version-aware. Sources: `src/vfs/AGENTS.md`, `goals/archive/G-058-static-runtime-packages.md`.
Follow-on: the next vfscommonupdate/bake promotion carries the coherent set together - src/lib/app-punkscript (pkgIndex + punkscript.tcl 1.2), punkboot core 0.6.0 and punkexe moduledoc 0.8.0 (plus punkboot moduledoc 0.3.1) - after which the baked kit serves 'help script' from the app-owned definition in internal mode; mixed intermediate states degrade gracefully as recorded in Progress => open
Follow-on: the next vfscommonupdate/bake promotion carries the coherent set together - src/lib/app-punkscript (pkgIndex + punkscript.tcl 1.2), punkboot core 0.6.0 and punkexe moduledoc 0.8.0 (plus punkboot moduledoc 0.3.1) - after which the baked kit serves 'help script' from the app-owned definition in internal mode; mixed intermediate states degrade gracefully as recorded in Progress => landed 2026-08-06 (the same promotion + bake event that landed G-170's coherent-set line, by then carrying app-punkscript 1.3 / core 0.7.0 / punkexe moduledoc 0.9.0; the deployed kit's 'help script' now renders the app-owned definition in internal mode)
Follow-on: extend app ownership to the other app-handled built-ins (shell/punk via app-punkshell, shellspy via app-shellspy) whose moduledoc entries are summary-level passthrough contracts today - same docs-package pattern, launcher_builtin_docpackages gains their entries => open
Follow-on: coherent-set promotion - the same vfscommonupdate/bake event as G-169's open promotion line, now additionally carrying punkboot core 0.7.0 + punkexe moduledoc 0.9.0 + app-punkscript 1.3 (with punk::args 0.18.0 + punk::ansi 0.2.0 for the landing report); mixed intermediate states degrade gracefully by construction (fence witness, guarded parse_report) => open
Follow-on: coherent-set promotion - the same vfscommonupdate/bake event as G-169's open promotion line, now additionally carrying punkboot core 0.7.0 + punkexe moduledoc 0.9.0 + app-punkscript 1.3 (with punk::args 0.18.0 + punk::ansi 0.2.0 for the landing report); mixed intermediate states degrade gracefully by construction (fence witness, guarded parse_report) => landed 2026-08-06 (promotion + bake: bootsupport punk::args 0.18.0 + punk::ansi 0.2.0; _vfscommon.vfs punkboot core 0.7.0 + punkexe moduledoc 0.9.0 + punkboot moduledoc 0.3.1 + app-punkscript 1.3; 11 kits rebaked and deployed - the deployed kit now serves narrowing, formhint labels and the parse_report dry-run, and the tclsh fence witness is satisfied so its dry-run is live instead of the historic ignored-tail render)
Follow-on: punkboot moduledoc registration guidance - note at the 'argsid' key that a multi-form project definition may carry its own '@cmd -formhint " <punkexe> help <sub> %formname%"' template now that the launcher narrows on form words (project parse=1 dry-run and narrowing already work; only the authoring hint is missing) => open
tcl::namespace::export length trim trimleft trimright INDEX INDEXCODE INDEXCHAR RANGE INSERT COUNT COUNT2 COUNT3 VIEW VIEWCODES VIEWSTYLE INDEXABSOLUTE INDEXCOLUMNS COLUMNINDEX NEW
tcl::namespace::export length trim trimleft trimright INDEX INDEXCODE INDEXCHAR RANGE TRUNCATE INSERT COUNT COUNT2 COUNT3 VIEW VIEWCODES VIEWSTYLE INDEXABSOLUTE INDEXCOLUMNS COLUMNINDEX NEW
#todo - expose _splits_ methods so caller can work efficiently with the splits themselves
#we need to consider whether these can be agnostic towards splits from split_codes vs split_codes_single
#[para]Returns the substring of string between the character positions startindex and endindex, inclusive, where the character positions are determined by INDEX. The returned substring will include any ANSI codes that are in effect for those characters.
#[para]Returns the substring of string between the character positions startindex and endindex, inclusive, where the character positions are determined by INDEX. The ANSI SGR codes in effect for those characters are re-applied at each plain-text run in merged (canonicalized) form - style-equivalent but not byte-identical to the original; non-SGR codes and codes after the last requested character are not re-emitted (see INDEXCODE end+1 for trailing SGR state).
#TODO - special case processing for end+n and equivalents to return trailing ANSI codes as well.
#[para]Returns string unchanged (byte-identical) if its grapheme count (as for COUNT) is at most maxgraphemes - otherwise returns the leading graphemes with the marker (default ...) appended, such that the result's total grapheme count equals maxgraphemes.
#[para]The kept prefix is extracted as for RANGE (merged SGR re-application); when that prefix carries ANSI codes an SGR reset precedes the marker so the marker and any following text render unstyled. The marker's grapheme count is charged against maxgraphemes; a marker that alone meets or exceeds the budget is itself truncated to maxgraphemes. Grapheme-count based, not display-column based.
error "punk::args::parse_report - internal argument processing mismatch for '$args'"
}
set id [lindex $tail 1]
if {[real_id $id] eq ""} {
error "punk::args::parse_report - no such id: $id"
}
set parseopts [list]
if {[dict get $opts -caller] ne ""} {
lappend parseopts -caller [dict get $opts -caller]
}
#a rejected line raises the same validation error punk::args::parse would -
#only successful parses have a landing report
set parsedresult [punk::args::parse $payload {*}$parseopts withid $id]
} else {
set parsedresult $payload
if {[catch {tcl::dict::size $parsedresult}] || ![tcl::dict::exists $parsedresult received]} {
error "punk::args::parse_report - first argument is not a punk::args::parse result dict (and no 'withid <id>' tail was supplied)"
}
}
#resolve the definition and the displayed form from the parse result
set docid [Dict_getdef $parsedresult id ""]
set real [real_id $docid]
if {$real eq ""} {
error "punk::args::parse_report - cannot resolve a registered definition from the parse result's id '$docid' - use the words form: parse_report <arglist> withid <id>"
}
set spec_dict [get_spec $real]
#G-046: expand display-deferred field content before display use (as arg_error does)
if {[tcl::dict::exists $spec_dict DISPLAY_DEFERRED] && [tcl::dict::size [tcl::dict::get $spec_dict DISPLAY_DEFERRED]]} {
set spec_dict [private::expand_display_fields $spec_dict]
}
set fid [Dict_getdef $parsedresult form 0]
if {![tcl::dict::exists $spec_dict FORMS $fid]} {
error "punk::args::parse_report - parse result names form '$fid' which is not present in definition '$real'"
}
set ARG_INFO [tcl::dict::get $spec_dict FORMS $fid ARG_INFO]
tcl::namespace::export length trim trimleft trimright INDEX INDEXCODE INDEXCHAR RANGE INSERT COUNT COUNT2 COUNT3 VIEW VIEWCODES VIEWSTYLE INDEXABSOLUTE INDEXCOLUMNS COLUMNINDEX NEW
tcl::namespace::export length trim trimleft trimright INDEX INDEXCODE INDEXCHAR RANGE TRUNCATE INSERT COUNT COUNT2 COUNT3 VIEW VIEWCODES VIEWSTYLE INDEXABSOLUTE INDEXCOLUMNS COLUMNINDEX NEW
#todo - expose _splits_ methods so caller can work efficiently with the splits themselves
#we need to consider whether these can be agnostic towards splits from split_codes vs split_codes_single
#[para]Returns the substring of string between the character positions startindex and endindex, inclusive, where the character positions are determined by INDEX. The returned substring will include any ANSI codes that are in effect for those characters.
#[para]Returns the substring of string between the character positions startindex and endindex, inclusive, where the character positions are determined by INDEX. The ANSI SGR codes in effect for those characters are re-applied at each plain-text run in merged (canonicalized) form - style-equivalent but not byte-identical to the original; non-SGR codes and codes after the last requested character are not re-emitted (see INDEXCODE end+1 for trailing SGR state).
#TODO - special case processing for end+n and equivalents to return trailing ANSI codes as well.
#[para]Returns string unchanged (byte-identical) if its grapheme count (as for COUNT) is at most maxgraphemes - otherwise returns the leading graphemes with the marker (default ...) appended, such that the result's total grapheme count equals maxgraphemes.
#[para]The kept prefix is extracted as for RANGE (merged SGR re-application); when that prefix carries ANSI codes an SGR reset precedes the marker so the marker and any following text render unstyled. The marker's grapheme count is charged against maxgraphemes; a marker that alone meets or exceeds the budget is itself truncated to maxgraphemes. Grapheme-count based, not display-column based.
error "punk::args::parse_report - internal argument processing mismatch for '$args'"
}
set id [lindex $tail 1]
if {[real_id $id] eq ""} {
error "punk::args::parse_report - no such id: $id"
}
set parseopts [list]
if {[dict get $opts -caller] ne ""} {
lappend parseopts -caller [dict get $opts -caller]
}
#a rejected line raises the same validation error punk::args::parse would -
#only successful parses have a landing report
set parsedresult [punk::args::parse $payload {*}$parseopts withid $id]
} else {
set parsedresult $payload
if {[catch {tcl::dict::size $parsedresult}] || ![tcl::dict::exists $parsedresult received]} {
error "punk::args::parse_report - first argument is not a punk::args::parse result dict (and no 'withid <id>' tail was supplied)"
}
}
#resolve the definition and the displayed form from the parse result
set docid [Dict_getdef $parsedresult id ""]
set real [real_id $docid]
if {$real eq ""} {
error "punk::args::parse_report - cannot resolve a registered definition from the parse result's id '$docid' - use the words form: parse_report <arglist> withid <id>"
}
set spec_dict [get_spec $real]
#G-046: expand display-deferred field content before display use (as arg_error does)
if {[tcl::dict::exists $spec_dict DISPLAY_DEFERRED] && [tcl::dict::size [tcl::dict::get $spec_dict DISPLAY_DEFERRED]]} {
set spec_dict [private::expand_display_fields $spec_dict]
}
set fid [Dict_getdef $parsedresult form 0]
if {![tcl::dict::exists $spec_dict FORMS $fid]} {
error "punk::args::parse_report - parse result names form '$fid' which is not present in definition '$real'"
}
set ARG_INFO [tcl::dict::get $spec_dict FORMS $fid ARG_INFO]
-encoding form falls through to the no-script form (stock
behaviour)."
@values -min 1 -max -1
scriptfile -type string -optional 0 -help -&
"Script file to source and exit. ::argv0 and 'info script' are
scriptfile -type string -optional 0 -&
-regexprefail {^-} -&
-regexprefailmsg -&
"a tclsh script file argument may not begin with '-' (stock parity: a line whose script-file position holds a dash-led word is the no-script form - all arguments stay in ::argv)" -&
-help -&
"Script file to source and exit. May not begin with '-' (stock
classification - a dash-led word in this position selects the
no-script form instead). ::argv0 and 'info script' are
the (normalized) script path; remaining args are ::argv. The
script may set ::tclsh(dorepl) 1 (piperepl runtimes) to enter
