punkshell

1 Tag

223 MiB

Author	SHA1	Message	Date
Julian Noble	8fa716b62b	G-176 achieved: override hints + 'package epoch' documented via stack-tied doc block (punk::ns 0.11.0, punk::libunknown 0.3.1; project 0.65.0) Increment 4 (the final increment) + the achieved flip. punk::ns 0.11.0: cmdinfo gains an 'overridden' result key - a second axis beside cmdtype/unavailable (the G-166 pattern) reporting the LIVE commandstack override state of the base command: one {renamer <string> docids <list>} dict per stack record (bottom-up), docids being the punk::args ids of doc blocks the record attached via 'rename_command -punkargs' (derived with punk::args::rawdef_id). Guarded live query - no hard commandstack dependency, empty when commandstack is not loaded, never cached so it is correct as stacks change. cmdhelp surfaces it: the table/string renders lead with a plain "note: '<cmd>' is currently overridden/extended via commandstack by: <renamers> (override-attached docs: '<ids>')" line, -return text leads with an OVERRIDDEN: line (below UNAVAILABLE when both apply), -return dict carries the key on all return shapes incl the undocumented fallback. punk::libunknown 0.3.1 (renamed from 0.3.0): the 'package epoch' subcommand is now DOCUMENTED - a substitution-free doc block with the space-form id {::package epoch} rides the override's commandstack record via -punkargs: mirrored for lazy pickup when punk::args loads after init (normal early boot), defined immediately when punk::args is present, and removed with the record by any removal path. 'i package epoch' renders real usage (all six grammar forms) - the doc gap that motivated the whole arc, retired. init's require tightened to 'commandstack 0.8-': a pre-mechanism stable copy fails pointedly at init instead of mid-call with a usage error (found via shadowing.test, whose require-based children needed 'package prefer latest' - the default stable preference picks a stale stable bootsupport commandstack over the alpha-versioned dev copy). End-to-end verified: 'i package epoch' renders the epoch doc; 'i package' leads with the note naming punk::libunknown and '::package epoch'; -return text/-return dict carry OVERRIDDEN:/the structured key; restore_original ::package removes doc and note. Tests: cmdhelp.test gains 2 hint pins (documented-command note incl docs clause + dict axis; doc-less-proc autodef render leading with the note, OVERRIDDEN: text lead, note clearing on unwind) and its two key-list pins (cmdhelp_cmdinfo_result_shape, cmdhelp_return_dict_valid) flip deliberately with the new key - exactly as they did for G-166's 'unavailable'. packageoverride.test gains the flagship pending-path pin (epoch doc mirrored pre-punk::args in path-cleared children, lazily defined on punk::args arrival, removed on unwind) and its pko_probe injects ::PKO_SRCMODULES. shadowing.test children set 'package prefer latest'. src/tests/modules/AGENTS.md punk/ns + punk/libunknown bullets updated. G-176 flipped ACHIEVED 2026-08-08: every acceptance clause met across the four increments (characterise -> migrate -> -punkargs mechanism -> hint + flagship docs). Detail file archived to goals/archive/G-176-commandstack-doc-integration.md with its two boot-site Follow-ons kept open (commandstack pre-sourcing at the libunknown-style boot sites; make.tcl skip-guard modernization - due by the 0.3.x/0.8.0 bootsupport promotion). GOALS.md entry removed; GOALS-archive.md record added; the one tree reference (packageoverride.test header) swept to the archive path. Project 0.64.0 -> 0.65.0 + CHANGELOG. Suites: libunknown+ns+commandstack+loadedlib 216/216; full modules tree 1354 total / 1343 pass / 11 constraint-skipped / 0 fail (zig-built tclsh90s 9.0.5); testbody_lint 1707 clean; goals_lint clean (79 active-index / 97 archived); make.tcl projectversion consistency OK. Claude-Session: https://claude.ai/code/session_01QgaxV27VZkmEec7oNbEVFc Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com	2 days ago
Julian Noble	ad0489b881	commandstack 0.8.0: rename_command -punkargs stack-tied doc blocks (G-176 increment 3; project 0.64.0) rename_command accepts a new leading option '-punkargs <list-of-definitionlists>' attaching punk::args doc blocks to the rename's stack record - e.g documenting a subcommand the override adds, with space-form ids such as {::package epoch}. Each element is one definitionlist exactly as given to punk::args::define (the same shape as a PUNKARGS variable element). Lifecycle: docs attach only when the rename lands (aborted renames return early) and are LIVE while the record is on the stack. The detach hook sits at remove_rename's doomed-record site - pop_rename, remove_renamer and restore_original all funnel through it - so every removal path removes the docs with the record. Works whether or not punk::args is loaded at rename time: deflists are mirrored in a new ::commandstack::stackdocs namespace registered inert into ::punk::args::register::NAMESPACES at module load (punk::args need not be present - the early-boot renames precede it), so a later-loading punk::args picks them up lazily; when punk::args is already present they are ALSO defined immediately (a namespace already consumed into loaded_packages never lazy-loads later appends; redefinition is idempotent). Detach removes one mirror occurrence per deflist and undefines via punk::args::undefine_deflist (deflist-keyed - commandstack never parses ids; never-defined deflists skip silently). Supported shape: one live record per doc id (same-id declarations in two records shadow; removing either removes the doc). The record carries the deflists under a trailing 'punkargs' key - the append-only key-order contract is preserved (token idx 0-1, renamer idx 2-3). The leading-option parse is generalised: -renamer/-punkargs in either order, both leading-only, non-dash word ends option scanning so misplaced options raise the pointed error. stackdocs state follows the 0.7.1 reload contract (info-exists guarded; registration idempotent across re-source). commandstack::help and the rename_command argdoc document the mechanism; the In-tree users line gains punk::libunknown (the increment-2 migration). commandstack.test: 5 new pins (docs live with the record incl key-order assertions, all four removal paths detach, the pre-punk::args pending path in a bare child that loads punk::args afterwards and lazily consumes the registered mirror, reload contract on mirror + single registration, option positions in either order + pointed misplacement) + 2 existing G-160 message pins updated to the generalised usage/misplacement wording (behaviour contracts unchanged). Suite 46/46. src/tests/modules/AGENTS.md commandstack bullet updated; goal Progress entry added. Project 0.63.0 -> 0.64.0 + CHANGELOG. Suites: commandstack 46/46; full modules tree 1351 total / 1340 pass / 11 constraint-skipped / 0 fail (zig-built tclsh90s 9.0.5); testbody_lint 1704 clean; goals_lint clean (80 active-index / 96 archived); make.tcl projectversion consistency OK. Claude-Session: https://claude.ai/code/session_01QgaxV27VZkmEec7oNbEVFc Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com	2 days ago
Julian Noble	a7bc62c3fb	punk::libunknown 0.3.0: ::package override installs via commandstack (G-176 increment 2; project 0.63.0) 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	2 days ago
Julian Noble	642fb265ea	G-176 increment 1 + active flip: ::package override characterisation - the pre-migration safety net (packageoverride.test, 11 pins) G-176 marked active (user-directed). New src/tests/modules/punk/libunknown/testsuites/discovery/packageoverride.test pins the CURRENT punk::libunknown ::package override ahead of the increment-2 migration onto commandstack::rename_command. BEHAVIOUR pins (must stay green byte-identically through the migration): 'package epoch tm\|pkg' single-arg forms, indexed '<which> <index> ?key?' queries, the four error arms, the filtered forget arm (real-ifneeded forgotten, no-ifneeded filtered out, tcl/Tcl/tcl::oo/tk denied, mixed lists partially applied), abbreviation acceptance (ep/epo/epoc + fo routing, with the parked builtin's rejection of 'ep' pinned as the override's deliberate delta), delegation pass-through, and the re-init no-op contract (stderr notice captured via a child ::puts shim). MARKED-TO-FLIP pins (comment-fenced to the increment-2 commit and no other): the install shape (::package origin = the ::punk::libunknown::package namespace import; :📦: parked and functional) and the two-override packagepreference interop children in BOTH real-world install orders (punkshell's pkgpref-first: stack count 1 + import origin; make.tcl's libunknown-first: stack count 1 + ::package proc origin). Children are fresh interps sourcing the source-tree libunknown/commandstack/packagepreference by path via a shared highest-version locator (discovery.test pattern). All 11 pins green on the first run against the live implementation. Tests AGENTS.md index updated; goal file gains its Progress entry. testbody_lint 1699 clean; goals_lint clean (80 active-index / 96 archived); modules tree 1346 total / 1335 pass / 11 constraint-skipped / 0 fail (zig-built tclsh90s 9.0.5). Claude-Session: https://claude.ai/code/session_01QgaxV27VZkmEec7oNbEVFc Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com	2 days ago
Julian Noble	b10abcbae0	G-176 drafted (proposed): commandstack doc integration - stack-tied overrider argdocs, override hints, libunknown package-override migration Four-increment arc from the 2026-08-08 feasibility investigation: (1) characterise the untested arms of the current punk::libunknown ::package override (epoch single-arg/indexed forms + error arms, the entire forget arm, abbreviation acceptance, delegation, re-init guard, packagepreference interop in both install orders; install-shape pins marked to flip), (2) migrate that override onto commandstack::rename_command (one managed stack for both live ::package overrides - cures the restore_original/wrong-command latent hazard of the current unmanaged mix), (3) rename_command -punkargs stack-tied doc blocks (attach at the single rename site, detach at the remove_rename choke point every removal path funnels through; stackdocs registered namespace covers renames performed before punk::args loads), (4) cmdhelp/cmdinfo override-in-place hint (G-166-style second axis, live get_stack query, no hard dependency) + the flagship {::package epoch} doc attachment and the commandstack::help how-to. Investigation evidence embedded in the goal Context: probe-verified space-form doc define/resolve/undefine/fallback cycle ('i package epoch' resolves despite the parent's restricted choices - G-051 space-form jump), record-key append contract, undefine_deflist primitive, no external :📦: callers, the dead has_package_files declaration, both real-world install orders. goals_lint clean (80 active-index goals / 96 archived). Claude-Session: https://claude.ai/code/session_01QgaxV27VZkmEec7oNbEVFc Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com	2 days ago

1 Commits (8fa716b62b8420264411c23d236c215719f152a2)