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
Acceptance: characterisation tests of the CURRENT libunknown override landed before any behaviour change and stayed green byte-identically through the migration (epoch single-arg/indexed forms + error arms, the forget arm, abbreviations, delegation, re-init guard, packagepreference interop in both install orders) with only marked install-shape pins flipping at the migration; libunknown installs its ::package override via commandstack::rename_command with a stack-query guard and no ::package:: residue; rename_command -punkargs docs are queryable while the record lives (incl renames performed BEFORE punk::args loads - pinned in a bare child) and are removed by remove_rename/pop_rename/remove_renamer/restore_original alike; cmdhelp shows an override-in-place notice (cmdinfo 'overridden' second-axis key, no hard commandstack dependency) enumerating record-attached doc ids; 'i package epoch' resolves the libunknown-attached doc and the how-to is described in commandstack::help + the rename_command argdoc; punk/libunknown, commandstack, punk/ns and punk/packagepreference suites pass under the canonical runtests interpreter.
Scope: src/modules/punk/args-999999.0a1.0.tm (parse paths, resolve directive handling for @leaders/@values); src/modules/punk/args/moduledoc/tclcore-999999.0a1.0.tm (sites carrying '#todo - fix -parsekey for leaders and values'); src/tests/modules/punk/args/testsuites/args/parsekey.test + testsuites/dev/parsekey-knownbugs.test (GAP/known-bug flips)
Acceptance: the three punkargsKnownBug tests in testsuites/dev/parsekey-knownbugs.test are enabled and pass (or are amended to the settled design and pass); the corresponding _GAP pins in parsekey.test are flipped or retired; the '#todo - fix -parsekey for leaders and values' moduledoc comment is resolved; the full existing punk::args suite passes untouched.
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.
@ -170,6 +170,31 @@ Increments land as separate commits, each leaving all suites green:
updated to the generalised usage/misplacement wording. Suite 46/46. Project
return "'$name' is a recognised name here, but is not available in this runtime/context - this command line is not usable here and the usage shown is reference documentation only."
}
#G-176: one-line override-in-place notice from cmdinfo's 'overridden' axis.
#basecmd is the command the records belong to (the cmdhelp subject);
#overridden is the list of {renamer .. docids ..} dicts (bottom-up). Returns
#the bare notice - the table render prefixes 'note: ', -return text prefixes
#0.11.0 - G-176 increment 4: cmdinfo gains an 'overridden' result key - a second axis beside cmdtype/unavailable (G-166 style) 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 (info commands on commandstack::get_stack) - empty list 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 - the G-166 leading-line convention), -return dict carries the 'overridden' key on all its return shapes, and the undocumented-command fallback carries the note too. The cmdhelp.test cmdinfo/dict key-list pins flipped deliberately with this key (as they did for G-166's 'unavailable'); new pins cover the documented-command note incl the docs clause + dict axis, and the doc-less-proc autodef render leading with the note, the -return text OVERRIDDEN: line and the note clearing when the override unwinds.
#0.10.0 - G-166 recognised-but-unavailable landings are surfaced distinctly. (a) cmdinfo gains an 'unavailable' result key on EVERY result - empty, or the canonical -choiceunavailable name (punk::args 0.16.0) the resolution addressed. It is a SECOND axis beside cmdtype, never a cmdtype value: cmdtype still answers what kind of executable thing was found ('string is dict' and 'string is true' on Tcl 8.6 both stay 'doconly'), availability answers whether the resolved word is selectable in this runtime/context. cmd_traverse's yielded/returned records carry a sixth element for it; cmdinfo keeps the final landing's value. (b) DECIDED (enacting the G-073 doc-walk follow-on): a unique PREFIX landing on an unavailable name now resolves that name's virtual docid, attributed - previously it conservatively resolved nothing, which made addressing inconsistent ('i string is tr' resolved but 'i string is dic' did not, while exact 'dict' and 'true' both did). The choice traverse's parse-parity claim is untouched: an unavailable word still identifies no SUBCOMMAND there, it is only attributed (the path taken when the name has no space-form virtual docid). (c) cmdhelp surfaces it in every return form: -return dict carries the key, table/string render the marking below the usage, -return text leads with an 'UNAVAILABLE:' line - and an unavailable subject is never presented as cleanly usable, so 'i string is dict 5' no longer renders info-scheme-clean just because the advisory parse of '5' succeeds against the virtual id. Wording (punk::ns::_cmdhelp_unavailable_marking) mirrors punk::args' tailored parse rejection; the runtime-specific why stays in the definition. Definitions without -choiceunavailable behave unchanged. Tests: cmdflow.test gains the flowunavail/flowunavail_nodoc fixtures + 5 pins, cmdhelp.test gains the helpstrua fixture + 5 pins (3 local, 2 real-world tclcore-gated) and the two deliberate key-list flips (cmdhelp_cmdinfo_result_shape, cmdhelp_return_dict_valid).
#0.9.3 - G-073 doc-walk parity: both cmd_traverse choiceword_match call sites (the G-051 space-form prefix-parity branch and the choice-traverse subcommand resolution) now pass the argument's -choiceunavailable list (punk::args 0.16.0 8th resolver argument), so the doc walk honours recognised-but-unavailable names identically to parsing: a prefix shadowed into ambiguity by an unavailable name resolves no documentation, and an unavailable word is not accepted as a choice (its documentation remains reachable via the exact space-form virtual docid, checked before the choice traverse - e.g 'i string is dict' on Tcl 8.6 via the tclcore moduledoc 0.4.0 per-class ids). No behaviour change for definitions without the key.
#0.9.2 - documentation-only PUNKARGS update: cmdhelp's 'subcommand' argument help now states the multi-form narrowing contract explicitly (argument words resolving to exactly one form narrow the usage display to that form's argument table, marked in the synopsis; no words, an ambiguous match, or words no form accepts keep the whole-command render). No behaviour change - the G-041 advisory-parse candidacy already implements it; G-150 pins the contract in cmdhelp.test against the now selection-sound punk::auto_exec::hash declaration (auto_exec 0.1.1).
#libunknown 0.3.1 attaches the {::package epoch} doc block to its override
#record. In these path-cleared children punk::args is ABSENT at init, so this
#exercises the real early-boot pending path: the deflist sits in the
#registered ::commandstack::stackdocs mirror, a later punk::args load
#consumes it lazily, and unwinding the override removes the doc with the
#record (the increment-3 detach contract, here through the real consumer).
test override_epoch_doc_attached {the override record carries the {::package epoch} doc - mirrored pre-punk::args, lazily defined when punk::args arrives, removed when the override unwinds}\
-constraints pko_sources -body {
pko_probe {
set r [list]
lappend r [llength $::commandstack::stackdocs::PUNKARGS]
lappend r [dict exists [lindex [commandstack::get_stack ::package] 0] punkargs]
lappend r [punk::args::id_exists {::package epoch}]
commandstack::restore_original ::package
lappend r [punk::args::id_exists {::package epoch}] [llength $::commandstack::stackdocs::PUNKARGS]
set r
}
} -result {1 1 1 0 0}
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}\
test cmdhelp_override_hint_documented_command {a documented overridden command renders the leading note naming renamer and attached doc id; dict form carries the overridden axis}\
set out [punk::ansi::ansistrip [punk::ns::cmdhelp ::testspace::ovfix]]
lappend result [string match "note: '::testspace::ovfix' is currently overridden/extended via commandstack by: ::testspace::ovrenamer*" [lindex [split $out \n] 0]]
lappend result [string match "*override-attached docs: '::testspace::ovfix zap'*" $out]
set d [punk::ns::cmdhelp -return dict ::testspace::ovfix]
#A doc-less overridden proc renders via the generate_autodef path (plain procs
#never take the 'Undocumented command' fallback) - the note still leads it.
test cmdhelp_override_hint_docless_and_text {a doc-less overridden proc leads its autodef render with the note (no docs clause); -return text leads with OVERRIDDEN:; the hint clears when the override unwinds}\
set out [punk::ansi::ansistrip [punk::ns::cmdhelp ::testspace::ovbare]]
#no -punkargs docs on this record - the notice line ends without a docs clause
lappend result [string match "note: '::testspace::ovbare' is currently overridden/extended via commandstack by: ::testspace::ovrenamer" [lindex [split $out \n] 0]]
lappend result [string match "*override-attached docs*" $out]
set t [punk::ns::cmdhelp -return text ::testspace::ovbare]
lappend result [string match "OVERRIDDEN: '::testspace::ovbare' is currently*" $t]
