The ::package override (the 'epoch' subcommand and controlled 'forget')
now installs via commandstack::rename_command -renamer punk::libunknown
instead of the former 'rename ::package :📦:' + namespace-import
mechanism. Both live ::package overrides (this and
punk::packagepreference's) now share one managed stack whatever the
install order - stack removals and third-party renames re-link correctly
instead of operating on the wrong command (previously commandstack's
::package stack believed the packagepreference wrapper was live while
libunknown's unmanaged import actually was; restore_original would have
stranded :📦:).
Migration deltas (exactly the set enumerated in the goal Context):
- the override body runs at :: - the four bare epoch_incr_pkg/epoch_incr_tm
calls are fully qualified (the old namespace-import execution context is
gone)
- the dead 'variable has_package_files' declaration dropped (its only use
was already commented out; the module-load probe stays)
- the two :📦: delegation sites (forget arm, default arm) now
delegate via COMMANDSTACKNEXT; :📦: no longer exists (nothing in
the tree called it)
- init does 'package require commandstack' (a no-op when already provided
- e.g whenever punk::packagepreference::install ran first, as in
punkshell boot; resolvable via tm paths in every other real init
context - bootsupport and the common vfs both carry commandstack-0.7.1)
- re-entry guard is now a stack query for the punk::libunknown record
(same 'already done' notice; the old ::punk::libunknown::package
proc-existence check tested a proc that no longer exists)
- init argdoc reworded; file renamed libunknown-0.2.4.tm ->
libunknown-0.3.0.tm (git mv + fossil mv) with Meta/manpage/provide-block
version updates and a changelog entry per the in-file bump procedure.
Behaviour of every subcommand arm is unchanged: all increment-1 BEHAVIOUR
pins in packageoverride.test passed byte-identically; only its four
MARKED-TO-FLIP install-shape pins flipped as fenced (origin ::package, no
:📦: residue, managed stack records - 1 solo, 2 in both
packagepreference interop orders). discovery.test and packageoverride.test
child interps now pre-source the source-tree commandstack by path (their
tm paths are cleared); libsearch/shadowing children resolve commandstack
via inherited parent paths and needed no changes.
Two out-of-scope items recorded as open Follow-ons in the goal (Scope
amendment needed if pursued): boot-site commandstack pre-sourcing
(punkboot core.tcl / make.tcl / punk::repl / punk::lib child-seeding - to
preserve the minimal-untracked epoch intent exactly) and make.tcl's
'info commands ::punk::libunknown::package' skip-guard modernization
(old kits still satisfy it; switch to a package-provide check before or
with the 0.3.0 bootsupport/kit promotion).
Goal Scope mirrors updated to the new filename (rename anticipated in the
Scope text). Project 0.62.2 -> 0.63.0 + CHANGELOG.
Suites: libunknown tree + loadedlib 42/42; full modules tree 1346 total /
1335 pass / 11 constraint-skipped / 0 fail (zig-built tclsh90s 9.0.5);
testbody_lint 1699 clean; goals_lint clean (80 active-index / 96
archived); make.tcl projectversion consistency OK (and that run itself
exercised the bootsupport-0.2.4 transition path live).
Claude-Session: https://claude.ai/code/session_01QgaxV27VZkmEec7oNbEVFc
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
Scope: src/modules/commandstack-999999.0a1.0.tm (rename_command -punkargs option, stackdocs pending-docs namespace, remove_rename detach hook, help/argdoc how-to); src/modules/punk/libunknown-0.3.0.tm (package-override migration to commandstack - fixed-version file, renamed from libunknown-0.2.4.tm at increment 2); src/modules/punk/ns-999999.0a1.0.tm (cmdhelp/cmdinfo override-in-place hint); src/tests/modules/punk/libunknown/testsuites/discovery/ (override characterisation arms - discovery.test extensions or a sibling packageoverride.test); src/tests/modules/commandstack/testsuites/commandstack/commandstack.test (-punkargs lifecycle pins); src/tests/modules/punk/ns/testsuites/ns/cmdhelp.test (override-hint pins)
Goal: a command overrider using commandstack can attach punk::args doc blocks that live and die with its stack entry (supplied at rename_command time, active whether or not punk::args is loaded yet, removed by every removal path), cmdhelp renders an override-in-place hint on any commandstack-managed command's existing documentation (naming the renamers and any doc ids their records added), and the punk::libunknown ::package override - the flagship consumer, whose 'package epoch' subcommand gains real documentation this way - is migrated onto commandstack so both live ::package overrides share one managed stack.
Acceptance: characterisation tests of the CURRENT libunknown override land before any behaviour change and stay green byte-identically through the migration (the epoch tm/pkg single-arg forms, indexed <which><index> ?keys...? queries and their error arms, the forget arm incl the tcl/Tcl/tcl::oo/tk denial and epoch-scripts pruning, abbreviation acceptance (ep/epo/epoc, fo/for/forge), a delegation pass-through pin, the re-init guard, and a packagepreference interop child covering both install orders) with only explicitly marked install-shape pins (::package import link, ::package:: parked name) flipping when the migration lands; libunknown installs its ::package override via commandstack::rename_command with a stack-query install guard mirroring punk::packagepreference and no ::package:: residue; commandstack::rename_command accepts a -punkargs list of definitionlists whose docs are queryable while the record lives - including renames performed BEFORE punk::args loads (pinned in a bare child that loads punk::args afterwards) - and are removed by remove_rename, pop_rename, remove_renamer and restore_original alike (record key appended per the key-order contract, reload-contract guard on new state); punk::ns::cmdhelp shows an override-in-place notice for a commandstack-managed command (cmdinfo carrying it as a second-axis key in the G-166 (achieved, see goals/archive/G-166-cmdinfo-unavailable-surfacing.md) style) without a hard commandstack dependency, enumerating record-attached doc ids; 'i package epoch' resolves the libunknown-attached doc in a punk shell and the mechanism how-to is described in commandstack::help and the rename_command argdoc; punk/libunknown, commandstack, punk/ns and punk/packagepreference suites pass under the canonical runtests interpreter.
@ -127,6 +127,46 @@ Increments land as separate commits, each leaving all suites green:
source the source-tree libunknown/commandstack/packagepreference by path via a
shared locator (discovery.test pattern). Tests AGENTS.md index updated.
@ -51,5 +51,5 @@ Unit tests for editable source modules under `src/modules/`, `src/modules_tcl8/`
- `punk/lib/` — punk::lib tests (`testsuites/lib/`): range/index/parse/compat/interp_sync utilities, G-058 static-baseline seeding (`staticseed.test`: interp_sync_package_paths/snapshot_package_paths propagate a simulated ::punkboot static baseline and seed `load {} <prefix>` ifneeded mappings; no-op without a baseline), and the repl command-completeness engine (`commandcomplete.test`: punk::lib::system::incomplete pending-opener stacks - the info-complete quoting quirk progression (`set x "{*}{"` standalone vs in-proc-body), single openers, tabs, escapes, incomplete<->info-complete parity property; pre-repl-refactor characterization, see goals/G-044 detail preserve-list)
- `punk/packagepreference/` — punk::packagepreference tests (`testsuites/packagepreference/`): G-058 static-vs-bundled policy (`staticpolicy.test`: require of a baseline package triggers the index scan before resolution so a newer bundled copy wins, static beats older bundled, exact requires of bundled versions stay reachable, missing static mappings get seeded), and the install re-install guard (`installguard.test`, G-160: second install returns 0 silently via the record `renamer` key - the historical `rename` read threw; uninstall/re-install cycle gets the next unique tokenid; fresh child interps source the SOURCE-TREE commandstack + packagepreference by path so no bootsupport/kit snapshot can answer)
- `punk/zip/` — punk::zip tests (`testsuites/zip/zipreader.test`, G-124 - the module's first tests): the dependency-free reader over the three archive shapes (bare zip, executable-prefixed with archive-relative offsets, executable-prefixed with file-relative offsets) - archive_info's offsetstyle/dataoffset derivation incl. the nozip verdict for a plain binary carrying a stray PK\5\6, members' per-entry introspection (classification, sizes, method, crc, mtime, stored attributes) and glob/exclude selection, unzip's byte-identical CRC-verified extraction incl. the >2MB streaming path and partial extraction; the named refusals (encrypted, unknown compression method, zip64, crc mismatch, path escape) each asserting that no partial output is left behind; and the mkzip->read round trip - the first coverage that what punkshell WRITES is readable. Runs entirely on stock Tcl (verified on msys2's tclsh8.6 with no zipfs, no vfs::zip and no tcllib); two zipfs-gated tests cross-check against a real zipfs mount and record the answer to the standing directory-classification question (zipfs keys on the trailing slash, not the stored permission bits - so punk::zip::mkzip directories mount as directories). The real-runtime pin self-gates on `bin/runtime/win32-x86_64/tclsh90b4_piperepl.exe`, which is untracked
- `punk/libunknown/` — .tm same-version shadowing pin-tests (`testsuites/shadowing/`): tcl::tm::add prepend rule, head-of-tm-list wins exact-version ties, version beats order, punk::libunknown parity — shipped behaviour depends on these (runtests tm ordering, punk_main package-mode precedence, G-033); mixed .tm/pkgIndex.tcl characterization is goal G-035; discovery/epoch-cache characterization (`testsuites/discovery/discovery.test`): sibling .tm registration happens only at the requested namespace depth (deeper modules invisible to 'package names' until requested), register_all_tm deep discovery (all-depths registration, per-epoch cached no-op, head-of-tm-list precedence parity), 'package epoch' command shape, trace-driven epoch increments on tm/auto_path changes, the epoch-index short-circuit (a .tm added to an already-scanned dir needs 'package epoch incr'), and the pkgIndex.tcl sourcing-scope contract (source_pkgindex, fixed 2026-07-11 - formerly a GAP pin of the global-'dir' clobber): user global 'dir' survives pkg-unknown fallthrough, index scripts see $dir and reach the real ::auto_path (tcllib extension pattern), and their stray unqualified sets no longer leak to ::; plus ::package-override characterisation (`testsuites/discovery/packageoverride.test`, G-176 increment 1, 2026-08-08 - the pre-migration safety net for the commandstack migration: epoch single-arg/indexed query forms and their error arms, the filtered forget arm incl the tcl/Tcl/tcl::oo/tk denial and the no-ifneeded filter, abbreviation acceptance (ep/fo prefixes the parked builtin rejects - a deliberate override delta), delegation pass-through, the re-init no-op guard, and MARKED-TO-FLIP install-shape pins (::package namespace-import origin, ::package:: parked implementation, commandstack::get_stack seeing only the packagepreference record in the two-override interop children covering BOTH real-world install orders - punkshell's pkgpref-first and make.tcl's libunknown-first) that flip only with the G-176 increment-2 migration commit). Suite conventions learned the hard way: child probes source the SOURCE-TREE libunknown directly by path — 'package require punk::libunknown' tie-breaks the same-version copies (src/modules vs bootsupport) by tm path order, which favours bootsupport in the testinterp and machine env paths in children; and probe scripts must avoid global variable names the handlers use (notably 'dir') — that clobbering misdirected a fixture write into the real Tcl install during test development
- `punk/libunknown/` — .tm same-version shadowing pin-tests (`testsuites/shadowing/`): tcl::tm::add prepend rule, head-of-tm-list wins exact-version ties, version beats order, punk::libunknown parity — shipped behaviour depends on these (runtests tm ordering, punk_main package-mode precedence, G-033); mixed .tm/pkgIndex.tcl characterization is goal G-035; discovery/epoch-cache characterization (`testsuites/discovery/discovery.test`): sibling .tm registration happens only at the requested namespace depth (deeper modules invisible to 'package names' until requested), register_all_tm deep discovery (all-depths registration, per-epoch cached no-op, head-of-tm-list precedence parity), 'package epoch' command shape, trace-driven epoch increments on tm/auto_path changes, the epoch-index short-circuit (a .tm added to an already-scanned dir needs 'package epoch incr'), and the pkgIndex.tcl sourcing-scope contract (source_pkgindex, fixed 2026-07-11 - formerly a GAP pin of the global-'dir' clobber): user global 'dir' survives pkg-unknown fallthrough, index scripts see $dir and reach the real ::auto_path (tcllib extension pattern), and their stray unqualified sets no longer leak to ::; plus ::package-override characterisation (`testsuites/discovery/packageoverride.test`, G-176 increment 1, 2026-08-08 - the pre-migration safety net for the commandstack migration: epoch single-arg/indexed query forms and their error arms, the filtered forget arm incl the tcl/Tcl/tcl::oo/tk denial and the no-ifneeded filter, abbreviation acceptance (ep/fo prefixes the parked builtin rejects - a deliberate override delta), delegation pass-through, the re-init no-op guard, and MARKED-TO-FLIP install-shape pins (::package namespace-import origin, ::package:: parked implementation, commandstack::get_stack seeing only the packagepreference record in the two-override interop children covering BOTH real-world install orders - punkshell's pkgpref-first and make.tcl's libunknown-first) - FLIPPED 2026-08-08 with the landed increment-2 migration as marked: they now pin the commandstack-installed shape, real proc at ::package, no ::package:: residue, both overrides as managed stack records (count 2 in both interop orders)). Suite conventions learned the hard way: libunknown 0.3.0 installs its ::package override via commandstack, so cleared-tm-path child probes must pre-source the SOURCE-TREE commandstack by path before libunknown init (children inheriting parent paths resolve it via require); child probes source the SOURCE-TREE libunknown directly by path — 'package require punk::libunknown' tie-breaks the same-version copies (src/modules vs bootsupport) by tm path order, which favours bootsupport in the testinterp and machine env paths in children; and probe scripts must avoid global variable names the handlers use (notably 'dir') — that clobbering misdirected a fixture write into the real Tcl install during test development
#MARKED-TO-FLIP (G-176 increment 2): these pin the CURRENT rename+import install
#mechanism - ::package is a namespace import of ::punk::libunknown::package and
#the previous implementation is parked at ::package::. The migration commit
#flips them to the commandstack-installed shape (real proc at ::package, no
#::package:: residue) and nothing else may.
#FLIPPED 2026-08-08 (agent, G-176 increment 2) as marked: previously pinned the
#rename+import mechanism (::package an import of ::punk::libunknown::package,
#previous implementation parked at ::package::). Now pins the commandstack
#install: real proc at ::package, no ::package:: residue, the override present
#as a managed stack record for renamer punk::libunknown.
test override_install_shape {current mechanism: ::package is an import of punk::libunknown::package and ::package:: holds the working previous implementation}\
test override_install_shape {commandstack mechanism: real proc at ::package, no ::package:: residue, the override a managed stack record}\
#The no-op contract (second init returns empty and leaves the install alone) is
#BEHAVIOUR and survives the migration. The message text and the import-shaped
#origin element are install-mechanism detail - MARKED-TO-FLIP with increment 2
#if the migrated guard reports differently.
#BEHAVIOUR and survived the migration; the guard is now a commandstack stack
#query for the punk::libunknown record but emits the same 'already done'
#notice. Origin element FLIPPED 2026-08-08 with increment 2 as marked.
test override_reinit_guard {a second init call is a no-op: empty return, an 'already done' stderr notice, install unchanged}\
-constraints pko_sources -body {
@ -247,18 +258,17 @@ namespace eval ::testspace {
[string match "*already done*" $::pko_captured]\
[namespace origin ::package]
}
} -result {1 1 ::punk::libunknown::package}
} -result {1 1 ::package}
# -- packagepreference interop - both real-world install orders ---------------
#punkshell boot: packagepreference (commandstack) first, libunknown on top.
#make.tcl: libunknown alone (packagepreference may arrive later).
#BEHAVIOUR pins: epoch answers and require chains down to the builtin in BOTH
#orders. MARKED-TO-FLIP pins: the commandstack ::package stack sees only the
#packagepreference record (1) while libunknown's rename is unmanaged, and in
#pkgpref_first order ::package is libunknown's import - increment 2 flips the
#stack count to 2 and the origin to the commandstack-installed proc.
#orders. Stack-count and origin elements FLIPPED 2026-08-08 with increment 2
#as marked: both overrides are now managed stack records (count 2) and
#::package is a commandstack-installed proc in both orders.
test override_interop_pkgpref_first {punkshell order: both overrides live - epoch and require both work; stack sees only the managed record (flips to 2)}\
test override_interop_pkgpref_first {punkshell order: both overrides live - epoch and require both work; both records on the managed stack}\
-constraints pko_interopsources -body {
pko_interop pkgpref_first {
set r [list]
@ -270,9 +280,9 @@ namespace eval ::testspace {
lappend r [namespace origin ::package]
set r
}
} -result {1 1.0 1 ::punk::libunknown::package}
} -result {1 1.0 2 ::package}
test override_interop_libunknown_first {make.tcl order then packagepreference on top: epoch reaches through the wrapper's delegation and require works; stack sees only the managed record (flips to 2)}\
test override_interop_libunknown_first {make.tcl order then packagepreference on top: epoch reaches through the wrapper's delegation and require works; both records on the managed stack}\
-constraints pko_interopsources -body {
pko_interop libunknown_first {
set r [list]
@ -284,6 +294,6 @@ namespace eval ::testspace {
lappend r [namespace origin ::package]
set r
}
} -result {1 1.0 1 ::package}
} -result {1 1.0 2 ::package}
}
tcltest::cleanupTests ;#needed to produce test summary line.
