- Repeated -include-paths flags previously overrode each other silently (standard
non-multiple punk::args opt semantics), quietly narrowing the test selection
while reporting green - a recurring misuse driven by Unix-CLI accumulate-flag
muscle memory (gcc -I / curl -H style).
- The option is now -multiple 1: repeated flags accumulate, the single
space-separated quoted list form is unchanged, and the unreceived default {**}
passes through (the consumer flattens occurrences with concat). Help text
documents both forms as equivalent.
- src/tests/AGENTS.md work-guidance updated. Known remaining sibling issue:
multiple trailing file-tail globs still silently match 0 files.
- Verified: repeated-flag and single-list invocations select identical file sets
(20 files / 189 tests) on Tcl 9.0.3, repeated-flag accumulation on 8.7, and a
no-flag default run with a file-tail glob unchanged. The general strict-arity
mechanism is proposed as G-053.
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
Five user-approved proposed goals with detail files, grounded in the 2026-07-10
characterization work (GAP pins in usagemarking.test/cmdhelp.test map to these):
- G-049 punk::args parse-status data model with machine-parsable cmdhelp returns:
documented per-argument status structure consumed by both arg_error renderers,
cmdhelp -return dict; fixes badarg coverage (type/allocation failures), scheme
honoured on failure path, caller attribution, and the stateful shared
colour-array scheme handling (nocolour fallthrough + dash-spelling leak).
- G-050 synopsis argument-validity marking and status-aware returns: 's' gains the
goodarg/badarg marking via the G-049 structure; replaces the curried-alias
excess-args length arithmetic with a parse against the resolved definition.
- G-051 cmdinfo truthful cmdtype for doc-only pseudo-commands + space-form docid
prefix parity via the shared choiceword_match resolver ('i string is tr').
- G-052 TclOO method-level autodef: undocumented methods get an (autodef) from the
introspected parameter list instead of the class-summary-only fallback.
- G-053 punk::args range-valued -multiple: {min max} occurrence ranges alongside
the legacy booleans, expressing "at most once, repeat is an error" without a
separate duplicates flag (mirrors the -choicemultiple precedent; motivated by
the runtests -include-paths last-wins incident).
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
- punk::args level (usagemarking.test, 14 tests): pins -parsedargs/-badarg/-scheme
marking primitives, goodchoice highlighting of selected and default-in-effect
choice words, and scheme border selection - asserted by SGR-parameter subset
against the live colour arrays. GAP pins for the documented -scheme choice
'nocolour' falling through to 'na' (renders with the previous scheme's leftover
colours) and the dash-spelling '-nocolour' leaking strike-only goodarg into the
shared colour array (G-049 candidates).
- punk::ns level (cmdhelp.test, 19 tests): pins scheme selection (error scheme on
failed parse of supplied args, info scheme + goodarg marking on success), badarg
marking via choiceviolation, the early alias-resolution branch, -return string
parity, goodchoice highlighting through cmdhelp, and the cmdinfo result shape.
GAP pins: pseudo-command cmdtype 'notfound' despite resolved docid + space-form
docid exact-word-only jump (G-051; real 'string is true'/'is tr' pins behind the
have_tclcoredocs constraint), TclOO undocumented-method class-summary fallback
with info-scheme parse of bogus args (G-052), synopsis marking absence and
curried-alias braced-target substitution (G-050), explicit -scheme ignored on
the parse-failure path and caller-attribution leaking cmdhelp's internal parse
source line at top-level call depth (G-049).
- punk::ns 0.1.3 (doc-only): cmdhelp 'subcommand' argument help rewritten - was
described as ensemble-subcommands-only; now covers tcl::oo methods and argument
words, and documents the info/error scheme display driven by argument validity.
- Verified: full punk::args + punk::ns suites green on Tcl 9.0.3 and 8.7.
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
textblock::table uses an unvalidated dict merge with no choice validation;
its PUNKARGS is incomplete and the -return -choiceprefix documentation
mismatch is the last open item from the punk::args -choices audit. This
goal proposes refactoring textblock::class::table's constructor to carry
inline punk::args define blocks (the class_ansi pattern) so the
constructor's documented option set becomes the single source of truth
that textblock::table's PUNKARGS references rather than a parallel
hand-typed list.
Assisted-by: harness=opencode; primary-model=openrouter/z-ai/glm-5.2; api-location=openrouter.ai
project::new documented -choices on -layout with -choiceprefix defaulting
to true (prefix matching promised), but the manual dict merge parser
accepted arbitrary values with no validation or normalization. Added
tcl::prefix::match against the documented layout choices so the parser
now validates and normalizes -layout values, matching the PUNKARGS
documentation.
Assisted-by: harness=opencode; primary-model=openrouter/z-ai/glm-5.2; api-location=openrouter.ai
install documented -choices on -overwrite, -source-checksum and
-punkcheck-folder with -choiceprefix defaulting to true, but the manual
dict merge parser validates option names only and never normalizes choice
values. PUNKARGS now declares -choiceprefix 0 so documented behaviour
matches the implementation (exact match required).
Assisted-by: harness=opencode; primary-model=openrouter/z-ai/glm-5.2; api-location=openrouter.ai
d/ documented -choices on the v argument with -choiceprefix defaulting
to true, but the manual parser uses an exact string comparison. PUNKARGS
now declares -choiceprefix 0 so documented behaviour matches the
implementation (exact match required).
Assisted-by: harness=opencode; primary-model=openrouter/z-ai/glm-5.2; api-location=openrouter.ai
renderspace -bias and -format, renderline -info and -overtext_type all
documented -choices with -choiceprefix defaulting to true, but the manual
switch-based parsers accept arbitrary values with no prefix matching.
PUNKARGS now declares -choiceprefix 0 so documented behaviour matches
the implementation (exact match required).
Assisted-by: harness=opencode; primary-model=openrouter/z-ai/glm-5.2; api-location=openrouter.ai
console_fact_get and console_fact_set documented -choices on the key
argument with -choiceprefix defaulting to true (prefix matching promised),
but the manual positional parser feeds key directly into a dict lookup
with no prefix normalization. PUNKARGS now declares -choiceprefix 0 so
documented behaviour matches the implementation (exact match required).
Assisted-by: harness=opencode; primary-model=openrouter/z-ai/glm-5.2; api-location=openrouter.ai
- .fossil-settings/binary-glob set to '*': binary checkins (e.g zips) proceed without fossil
warnings/prompts; the aim of an eventually binary-free tree (G-004/G-005/G-006) is
agent/workflow policy, deliberately not enforced at the local VCS layer
- .fossil-settings/AGENTS.md: new "Commit warning suppression" contract documenting the above
- root AGENTS.md: LF preference clarified - converting CRLF text files to LF when editing is
correct (no CRLF preservation for diff-minimisation; preserve only deliberately mixed-ending
files or on explicit instruction); binary-checkin bullet notes the VCS-layer carve-out
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
The testinterp replaces auto_path wholesale (project src/lib dirs, root
lib_tcl<N>/<arch>, [info library] + parent). Under a kit executable that
parent is e.g //zipfs:/app, and tclPkgUnknown scans only an entry plus its
immediate children - so kit-bundled packages under //zipfs:/app/lib_tcl<N>/
<pkg> (e.g tcllib's tcl::chan::fifo2, required by the shellrun harness at
testinterp setup) were unreachable. Unnoticed in punkshell because the
project's own root lib_tcl9/win32-x86_64 carries tcllib2.0; projects
without that payload (e.g tomlish) failed every file at
'package require shellrun' when run under a punk kit exe.
Now the kit's internal lib/lib_tcl<N> dirs are appended when present,
mirroring the internal-path classification in src/vfs/_config/punk_main.tcl:
zipfs app mount, tclkit ::tcl::kitpath exe dir-shadow, cookfs //cookit:/
volume (default mount name only, as per punk_main.tcl). No-op under native
tclsh. Verified: punk902z + tclsh902z suites pass; classification probed OK
under tclkit 8.6.17, punk9cook (cookit), punk91 (zipfs 9.1), native Tcl903;
tomlish suite under punk902z/punk91 goes 0 -> 149/149 with the same edit.
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
makeFile/makeDirectory output previously landed in the working directory -
aborted core exec.test runs littered src/tests with untracked helper files
(cat, echo, gorp.file ...). Unless -tcltestoptions supplies -tmpdir, a
fresh directory from 'file tempdir' (TMPDIR/TEMP/TMP + pid fallback for
tcl 8.6) is configured and deleted before exit; a hard-aborted run now
leaves litter in the OS temp area rather than the source tree.
Takes effect in single-process mode; multi-process mode still does not
forward tcltest options to child processes (pre-existing todo).
Contract documented in src/tests/AGENTS.md.
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
TIP 746 (Tcl 9.1) removed lseq's expr-operand behaviour. punk::lib::range
(lseq branch) now normalizes int[+-]int offsets via offset_expr so callers
like `range 0 [llength $list]-1` keep working (punk::ansi::grepstr broke
under 9.1b0, taking example-block highlighting and the punk::args
examples.test with it). The lseq branch is also aligned with the tcl8
fallback contract: default 'by' now infers direction (descending ranges
previously returned empty under tcl9) and 'by 0' returns empty (Tcl 9.1
lseq changed by-0 to return one element).
Direct lseq expression operands expr-wrapped: punk::lib lzipn_tcl9b/c,
cols, cols2; punk::args zero_based_posns.
check::has_tclbug_safeinterp_compile falls back to interp invokehidden
tcl:unsupported:disassemble - Tcl 9.1 safe interps hide tcl::unsupported::*.
New modules/punk/lib range.test pins the range contract on 9.0 and 9.1;
core tests AGENTS.md documents native-tclsh vs punk-exe exec.test baselines.
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
Rework the proposed G-047 for mixed git/fossil-preferring teams: committed
[workflow] vcs in punkproject.toml declares the team primary (authoritative
interchange); the same key in an uncommitted punkproject.local.toml redirects
an individual developer's unqualified commit instructions. Resolution order:
local override > project field > filesystem detection. Drops the
one-directional batched-checkin claim (developer committing granularly to the
secondary owns batching up to the primary) and records that punk internal
machinery (punkcheck related-project tracking, G-027 pull, G-016 discovery)
stays standardized on fossil regardless of the declared field. New detail
file records rejected alternatives and rationale.
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
Both user-approved, drafted from the 2026-07-09 characterization findings with
their acceptance criteria anchored to the pinned GAP tests.
- G-045 (authoring ergonomics): parser-recognised record continuation
(candidate: unquoted trailing -& with collision rules and an element-count
disambiguation alternative recorded), @cmd honouring -unindentedfields,
constructed (string-built) definitions able to opt into the whole-block
indent normalization file-style definitions get (de-hacking
::punk::helptopic::define_docs as the consumer proof), and the
braced-vs-quoted container quoting rules promoted from defquoting.test into
the define documentation.
- G-046 (deferred -help + fixes): headline item per user emphasis at approval
- argument resolution stops processing -help/display-only fields, deferring
their tstr expansion to display time with separate parse-vs-display caching
(per the existing in-source review note), for measurable first-parse gains
and fixing the reentrancy class reproduced with punk::ansi::mark_columns
(~3.94s first call: its -help calls a proc that calls mark_columns, whose
parse resolves the same still-resolving definition). Plus: @dynamic
second-round multiline paramindent alignment, prefix-normalization value
shape (list-wrap of backslash-containing choices), -return string renderer
cmd-help continuation alignment, and the misleading goodargs 'Bad number of
leading values...' prefix in 'i <cmd> <args>' output.
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
Tests-first coverage pass (user-directed) before any changes to the
definition-parsing/indentation machinery. punk/args suite: 128 tests, 15 files.
- rendering.test (15): nesting independence (plain + tstr definitions render
identically regardless of source-block indentation), relative-indent
preservation (2-space help and 1-space choicelabel conventions, single and
multiline - preservation, not enforcement), -unindentedfields (arg -help
works left-margin; @cmd accepts-but-ignores it - GAP pinned), constructed
(string-built) definition absolute-indent characterization ('constructed'
to avoid confusion with the @dynamic directive), multiline ${[cmd]}/${$var}/
resolved_def insertions (aligned at insertion column, nesting-independent),
and @dynamic ${$DYN_X} double substitution: stable across repeated
resolutions, provider refresh honoured in help text, choice display and
parse acceptance, textblock::frame-style art choicelabels byte-aligned -
but multiline -help insertions land lines 2+ at insertion-4 (GAP pinned:
the second-round subst path lacks paramindent re-alignment)
- choicegroups.test (5): group/-choices union parsing, cross-group prefixes,
duplicate-entry dedup, per-group titled choice tables (the punk::imap4
multi-table display), imap4-style {\Deleted}/{$MDNSent} values with labels
incl. through tstr-bearing blocks; GAP pinned: prefix-normalization
list-quotes special-character choices (exact '\Deleted' stores the plain
string, prefix '\De' stores a one-element list) - value shape depends on
input style
- defquoting.test (3): container quoting rules pinned - braced values fully
literal ($, [], two-char \n, bare backslashes), quoted values get Tcl
backslash semantics (\n -> newline, \ -> \) with $/[] still literal, and
\$\{...\} renders a literal ${...} in tstr-processed blocks
- examples.test (6): helpers::example box/title/-tstr toggle (no-dedent
direct-call contract pinned), ${[example ...]} insertion into @cmd help
(bars at insertion column, content +2, automatic 'Example: eg <id>' row),
@examples -> punk::args::eg with #<nodisplay>/@#<nodisplay> stripping
(ANSI-tolerant), strip_nodisplay_lines unit, live tclcore ::lseq smoke
- punk::args 0.3.1: helpers::example -title path called bare [a] (resolvable
only where a punk shell's global alias exists - errored under plain tclsh);
now punk::ansi::a. Found by examples.test in the runtests environment.
- investigated punk::ansi::mark_columns first-call slowness (3.94s first,
60us after): argdoc -help calls a proc that calls mark_columns, whose parse
resolves the same still-resolving definition - hazard already documented
in-source with candidate fixes; recorded in CHANGELOG for goal
consideration, deliberately not patched
- project 0.4.11 (CHANGELOG entry)
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
Activated and completed under user direction (2026-07-08). Aliases for choice
values are now first-class: accepted at parse, normalized to their canonical
choice in results, folded into the canonical entry in usage display, and
resolved identically by the punk::ns doc-lookup walk.
- punk::args 0.3.0:
* -choicealiases {alias canonical ...} on argument lines; dict shape
validated in the option switch, alias->existing-choice and no-collision
cross-validated after spec merge (surfaces at resolve time - define is
lazy)
* the choice-word matching chain extracted from get_dict into the shared
resolver punk::args::choiceword_match {word nocase allchoices
choicealiases choiceprefix denylist reservelist} -> {matched exact
canonical}; get_dict delegates to it (writeback/lset logic stays at the
call site) - one implementation for parser and doc walk
* exact aliases match under any -choiceprefix/-nocase setting; alias names
join the prefix-calculation pool when -choiceprefix is true; deny applies
to the matched NAME (denied alias requires the full alias; a canonical
reached via its alias is exempt from the canonical's own deny entry)
* display: aliases fold into the canonical entry as an '(alias: x)' /
'(aliases: x|y)' label note (single convergence point covers all render
paths); alias names join the display prefix calculation so highlighted
minimal prefixes stay truthful
* define doc gains the -choicealiases section
- punk::ns 0.1.2: cmd_traverse resolves subcommand words via choiceword_match
- -choiceprefixdenylist/-choiceprefixreservelist now honoured in doc lookup
(the two pinned parity GAP tests flipped to agreement), aliases normalize
before choiceinfo lookup, -nocase honoured in the walk
- punk 0.2.3: punk::help adopts the feature - 'i help' lists one entry per
registered topic (topics+help, tcl, env+environment, console+term|terminal);
topic words accept aliases and unique prefixes with the user-decided
minimum-prefix policy recorded in ::punk::helptopic: denylist {help}
(h/he/hel stay command words), reservelist {c to tc} (fall through to
command lookup; e/en and te/ter fall through naturally as ambiguous).
Argless 'help' output byte-identical to the strict-80 baseline.
- tests: choices.test +5 (alias exact/prefix normalization, noprefix exact-
only, nocase, the punk::help policy matrix, resolve-time validation);
cmdflow.test parity tests flipped from GAP to agreement + alias-traverse and
display-fold assertions (+flowaliased fixture)
- suites: punk/args 98 pass + 1 skip, punk/ns 28 pass, punk/lib 21 pass
- G-040 flipped active -> achieved 2026-07-08; detail file records
implementation and verification
- project 0.4.10 (CHANGELOG entry)
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
From interactive review of the help restructure: 'i help' / 'i help <topic>'
usage tables rendered ~160 columns wide. Only the argless 'help' overview is
strictly 80-column - but the rest should stay reasonable, and the usage tables
do not yet wrap to terminal width, so punk::args source line lengths directly
set table width.
- helptopic argdoc help texts manually folded at ~70 columns ('help tcl' was
the worst offender at ~230 chars on one line)
- generated ::punk::help/::punk::help_chunks definitions: basehelp/topichelp/
chunks-note folded; topic choice grid rendered with -choicecolumns 2 (the
largest width contributor)
- dynamically built definitions don't get the file-sourced indentation
normalization - topichelp's continuation over-indented, fixed with an
explicit \n join
- results: i help 68 cols, per-topic 61-65; argless 'help' output byte-
identical to the strict-80 baseline; punk/ns 26 and punk/args 93+1 suites
pass
- future improvement noted in CHANGELOG: automated (potentially language-
dependent) wrapping of help text to available width, e.g. via tcllib's
text-adjust facilities
- project 0.4.9 (CHANGELOG entry)
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
New 'make.tcl vfslibs' step (also run inside 'make.tcl project' before kit vfs
assembly): propagates declared vendored platform-library packages into kit vfs
lib_tcl<N> trees, ending the hand-copying that let kits ship a known-buggy
tcludp through three make invocations (the G-036/G-037 motivating case).
- declaration: src/runtime/vendorlib_vfs.toml, parsed with bootsupport tomlish
(no ad-hoc parsing; G-024's mapvfs toml conversion NOT required first - this
file is recorded as a candidate for absorption into it). [install.<name>]
entries: source (relative to src/), targets (kit vfs lib folders relative to
src/vfs/), optional supersedes (folder names removed from each target before
install - explicit, no silent mixed-version provision per G-035 concerns).
- participation is per-package per-kit; authority is the declaration - nothing
syncs undeclared, so the known vendorlib/kit twapi drift is deliberately
untouched (resolves the direction/authority design question).
- punkcheck provenance at src/vfs/.punkcheck (gitignored, outside kit
payloads); skip-if-unchanged proven (rerun: 0 copied, 9 skipped per target);
malformed/unresolvable entries fail the build naming the entry (exit 3).
- 8.6 kits upgraded (the G-036 loose-end decision, recorded): tcludp 1.0.13 is
dual-generation (pkgIndex selects tcl9udp1013.dll on 9+, udp1013t.dll on
8.5+) so the single vendorlib_tcl9 source serves punk8win.vfs/lib_tcl8;
superseded udp1.0.12 removed.
- verified on rebuilt kits: punksys/punkbi (8.6.13) and punk902z (9.0.2) all
report package require udp == 1.0.13 loading the generation-appropriate dll
from their vfs; no udp1.0.12 remains under src/vfs; punksys piped-shell exit
smoke clean.
- G-037 flipped proposed -> achieved 2026-07-08 under user direction (no
intermediate active stop).
- includes project-build byproducts via established channels: bootsupport
snapshots refreshed to punk-0.2.1 / punk::lib-0.3.0 (from today's version
bumps) and make.tcl synced into layout copies.
- project 0.4.8 (CHANGELOG entry)
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
Completes G-036's remaining acceptance item - version-based detection of the
vulnerable combination (tcludp < 1.0.13 on Tcl 9 Windows: the per-thread exit
handler closes the process-global sockListLock/waitForSock events, silently
freezing every other udp-using thread's event loop after any udp-loaded thread
exits; root-caused and fixed-by-upgrade in 0.4.3).
- punk::lib 0.3.0: has_libbug_udp_threadexit gathers live facts (loaded udp
version, else best available registered version discovered without loading
the binary via an unsatisfiable package require triggering the index scan)
and delegates the verdict to the pure classifier
libbug_udp_threadexit_applies (facts in, verdict out - testable). has_libbug_*
is the new check family for bundled/vendored library bugs; buginfo dicts may
carry a full 'url' reference key for non tcl-core trackers.
- punk 0.2.1: 'help tcl' scans has_libbug_* alongside has_tclbug_*, renders the
url key when present, and no longer errors on a triggered check carrying a
reference without a description (latent unset-indent fix).
- new checkbugs.test: classifier combination matrix, live-check dict shape and
classifier consistency, and a buginfo-contract test across all existing
check procs.
- verified: current kit (udp 1.0.13) reports bug=0 with no warning; a simulated
triggered has_libbug_* check renders description + url in the help tcl
warning block. Suites: punk/lib 21 pass, punk/ns 26 pass.
- G-036 flipped to achieved 2026-07-08 (index acceptance REMAINING annotated
DONE; detail file gains the Detection section). Open non-gating decisions
recorded in the detail file: punk8win (8.6) kit udp 1.0.12 swap; optional
upstream tickets for residual tcludp trunk weaknesses.
- project 0.4.7 (CHANGELOG entry)
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
User-approved goal for interactive command completion and hinting in the repl
(raw mode primary), driven by the punk::args documentation corpus:
- command-word resolution via the same doc-lookup flow as 'i' (ensembles,
subcommands, ensemble parameters - characterized in cmdflow.test), argument
position via the definitions (options, choices with parse-consistent
prefix/deny/reserve matching, literals, multi-form awareness per G-041)
- activation preserves the editbuf's literal-tab support (tab is content in
this shell - completion cannot exclusively claim plain Tab; trigger scheme
decided and recorded at implementation)
- per-subshell completion-provider seam: the punk::args completer is the
default provider; a subshell can declare an alternative or none - minimum
bar is a clean disable for language subshells such as an interactive xtal
session (full xtal completion out of scope, not precluded)
- introspection must not execute candidate commands (arginfo principle);
no per-keystroke terminal queries added when idle (G-013 approach note)
Detail-file weaves from the same direction:
- G-041: form candidacy should be exposed as an API accepting PARTIAL argument
lists (per-form compatibility while typing) for the G-044 hinting consumer
- G-043: subshell definitions gain a repl-behaviour composition aspect
(completion/syntax provider); xtal-style language subshells recorded as the
motivating scenario, an actual xtal session deferred to its own future goal
- G-013: raw editor essentials noted as G-044's prerequisite; the editbuf
literal-tab constraint recorded as a standing approach note
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
Both user-approved after a review of the intended plugin facility (punk::mix::init
pluginmgr todos, the punk::pluginmgr 0.5.1 tcllib fork, punk::cap provider/handler
system, punk::cap::handlers::templates pathtype resolution, punk::overlay
commandset composition and its toml-CLI todo).
- G-042: a named subshell declares help topics (name/aliases/summary/text) in
punk::config stored configuration, registered into the ::punk::helptopic
registry on entry and restored on exit, with an explicit shadowing policy.
Text-content only - config is data; code-bearing topics belong to the plugin
path where the trust story lives. Detail file records the registry seam
(punk 0.2.0), dependencies (hard on G-014; beneficial G-040/G-008/G-009),
and the plugin-facility relationship from the review.
- G-043: the umbrella for that plugin path - a punk.subshell capability whose
providers supply commandset bindings (punk::overlay import), help topics
(G-042's registry API) and config defaults per named subshell, with a
validating punk::cap handler, an equivalent data-only stored-config
declaration path (absorbing punk::overlay's ".toml configuration files for
defining CLI configurations" todo), and punk::pluginmgr as the discovery/
safe-interp trust layer for untrusted providers. Also absorbs punk::cap
housekeeping found in the review: pkg_unregister api-object cleanup and
unhandled-capability discoverability (the deliberate punk.isbogus silence).
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
- commented out five development trace puts in the doc-lookup machinery:
"PROC auto def"/"ENSEMBLE auto def" (generate_autodef) were emitted on STDOUT
and polluted 'i'/'s' output in script/exec contexts (agent-facing per the
G-015 piped-call pattern); "cmd_traverse - skipping to documented subcommand"
(space-form id path), "---> cmd_traverse ensembleparam" (ensemble -parameters
traversal) and "cmd_traverse 10 ... - review" (fallthrough return) were
stderr noise. No functional change.
- cmdflow.test: 8 new tests characterizing ensemble -parameters handling in the
doc-lookup flow (the punk::netbox::man pattern - leading apicontextid before
the subcommand at every ensemble level):
* generate_autodef models each -parameters entry as a -ensembleparameter 1
leader with @leaders min/max = nparams+1 (single- and two-param fixtures)
* cmd_traverse consumes parameter words and resolves the subcommand's
explicit or autodef docid, re-presenting the parameter in args_remaining
so the subcommand's own leader-based definition (as punk::netbox::man's
explicit defs model the curried parameter) can parse it
* nested sub-ensembles with their own -parameters re-consume the curried
parameter at each level
* punk::args::parse treats -ensembleparameter leaders as ordinary named
leaders; cmdhelp renders a documented subcommand's usage through the
parameter (end-to-end smoke)
- suites: punk/ns 26 pass (was 18), punk/args 93 pass + 1 skip (unchanged)
- project 0.4.6 (CHANGELOG entry)
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
- fixed "@opts -any 1" (arbitrary/adhoc option passthrough): an option not in
the definition crashed get_dict with "can't read argname" at the name-mapping
stage - adhoc opts now fall back to their raw supplied name, under which
argstate/arg_checks were already populated at scan time (real consumers:
vendored tomlish definitions declare -any 1)
- commented out a debug puts stderr (">>>_get_dict_can_assign_value NOT
alloc_ok...") that fired on every failed clause type assignment (visible on
any multiform parse miss; its happy-path twin was already commented)
- new forms.test (8 tests): @form spec structure (form_names, shared
{a b}-prologue blocks), explicit -form by name/index with cross-form
rejection, multiform synopsis rendering, and GAP pins for G-041 - default
parse is effectively form-0-only, -form rejects the documented list-of-forms
usage, and @form -synopsis overrides are stored in the spec but ignored by
synopsis rendering
- new validation.test (11 tests): -type validation matrix, -range/-minsize/
-maxsize, -nocase choice normalization, option -multiple accumulation,
required-option enforcement, unknown-option rejection vs -any adhoc
passthrough (the bugfix's regression test), -- end-of-options marker,
@values -max enforcement, received-key clause ordinals, solos list, and
default-vs-received distinction
- src/tests/AGENTS.md: note that tcltest compares the -body return value -
bodies ending in a loop must end with an explicit 'set result'
- suites: punk/args 93 pass + 1 skip (was 70+1), punk/ns 18 pass; full
source-tree run 569/581 with only the known exec-14.3 baseline failure
- project 0.4.5 (CHANGELOG entry)
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
User-approved goal recording the multi-form feature gap characterized 2026-07-08
with an after-like fixture:
- punk::args::parse without -form (default *) does not attempt non-zero forms -
input matching only a later form (e.g. 'cancel after#1') fails with form 0's
type/arity error, so the appropriate form must currently be specified manually
- -form is documented as accepting a set/list of forms but accepts only a single
form name or integer index
- the documentation surface does not determine/mark the closest form
('i after cancel <id>' presents the default form; 's after cancel someid'
lists all synopses unmarked)
Detail file records the probe findings, an approach sketch (form candidacy with
a leading-literal fast path, -form list support, doc-surface marking), the
requirement that explicit single-form restriction remains available, and the
test-first sequencing (forms.test GAP pins flip when this goal is implemented).
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
- GOALS.md: G-040 punk::args choice aliasing with parse normalization, display
folding, and doc-lookup parity (user-approved); detail file records the
prefix/deny/reserve collapse analysis from the punk::help work, the
cmd_traverse divergence, the c/to/tc minimum-prefix policy question, and the
test-first sequencing
- new punk/ns cmdflow.test (10 tests): cmdwhich/cmdinfo/cmd_traverse docid
flow - direct, via-alias and subhelp-choiceinfo resolution (exact + unique
prefix), unknown-word fallback to parent docid, -choiceprefix 0 exact-only,
space-delimited ids, cmdhelp -return string smoke; the parse-vs-doc-walk
divergence (deny/reserve lists honoured by punk::args::parse, ignored by the
cmd_traverse walk) pinned as GAP tests pending G-040
- choices.test: 4 new unrestricted-mode (-choicerestricted 0) tests - prefix
normalization to the canonical choice, unknown/ambiguous passthrough,
denylist and reservelist passthrough, and the punk::help collapse recipe
(prefix+deny+reserve on a -multiple leader)
- punk::args 0.2.2 (doc-only): define doc -choice* fields now state the
-choicerestricted 0 passthrough semantics, -choiceprefix result
normalization + minimal-prefix display highlighting, denylist behaviour for
shorter prefixes in both restricted modes, and the reservelist phantom-entry
idiom for per-choice minimum-prefix control
- suites: punk/args 74 pass + 1 skip (was 70+1), punk/ns 18 pass (was 8)
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
- each topic (topics|help, tcl, env|environment, console|term|terminal) is a
handler proc returning {channel text} chunks, with its own punk::args
definition (id ::punk::helptopic::<topic>) so 'i help <topic>' renders
documented usage
- registering a topic (re)generates the ::punk::help / ::punk::help_chunks
definitions, so 'i help' shows a documented topic table that always matches
the registry (previously an autogenerated stub); the registry is the seam
for future subshell-declared topics
- 'help topics' derived from the registry (all aliases listed, fits 80 cols)
- no-arg overview and command-fallthrough output byte-identical to before;
80-column layout preserved; verified on tcl 9 and 8.6 kits via the script
and shell subcommands
- 'help env' degrades to a one-line notice when punk::config is not
initialised (e.g. script contexts) instead of an error stack + exit 1
- shared table_block helper destroys table objects after print (previously
leaked several per help invocation)
- project 0.4.4 (CHANGELOG entry)
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
Policy (GOALS.md maintenance rules, mirrored in root AGENTS.md and goals/AGENTS.md):
- agents apply goal-entry adds/edits only on user request, proposal-first: show the
proposed wording and get explicit approval before writing (replaces "only the user
adds or edits goals" - the user was applying agent-drafted edits by hand anyway)
- suggesting candidate goals is welcome and encouraged when grounded in the work at
hand; a suggestion is a flagged proposal, never a file edit; bulk goal surveys stay
out of bounds
- detail-file updates from user-directed work on a goal proceed without pre-approval,
reported in the completion summary; index stays canonical
- unchanged: achieved-flip on met acceptance (reported), no proposed->active flips
G-038 (user-approved):
- Acceptance gains a post-restart terminal-query clause: a code-interp query (e.g.
'help console') must succeed instead of being refused by the stale settled
can_respond=0 anchor
- detail file records the proven mechanism for the post-restart console failure
(piped phase settles can_respond=0; punkshell.tcl opens CONIN$ as a new channel
leaving the repl thread's stdin as the exhausted pipe; the anchored default console
keeps the dead pair; forced resettle honestly re-settles 0 via layer-1 eof), the
rebind requirements (re-point {in out} AND unsettle), and the hidden-console
repro/regression harness
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
- G-039 (proposed): investigate/reproduce the orphaned-shell one-core spin
observed 2026-07-08 (single hard-looping thread after the hosting terminal
went away); detail file records the observation, repro/diagnosis approach
(reusing the G-036 dump tooling pipeline) and the G-038 coordination point
(dead console = failure branch of the console-EOF restart decision).
- G-036 acceptance reworked per user: standalone minimal repro waived as
moot (root cause proven and fixed upstream); remaining actionable is a
has_bug-style check reporting tcludp < 1.0.13 on Tcl 9 Windows through the
existing check/help machinery (simple version test, no behavioural probe).
Index and detail-file acceptance kept in sync.
- AGENTS.md User Preferences: cmd.exe truncates a heavily populated PATH -
tools resolvable in PowerShell may be not-found under cmd /c; use absolute
exe paths there and suspect truncation before absence.
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
G-036: the CloseHandle trap script is embedded in the detail file (was a
dangling reference to session-ephemeral scratchpad). G-038: the
repl::reopen_stdin race analysis from the G-036 investigation is written in
(the prior cross-reference pointed at content that existed only in
conversation), and the goal now explicitly owns that path's fate - it runs
for real on console-EOF at an interactive prompt, and the caller-driven
restart should cover that scenario so reopen_stdin can be retired. G-037:
twapi vendorlib(5.0b1)/kit-vfs(5.2.0) drift recorded - divergence exists in
both directions, so the sync step needs explicit authority semantics.
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
User note recorded: with per-subshell configs (G-008/G-009), piping
`subshell <name>` then going interactive should reasonably land IN that
subshell (quit unwinding to the initial shell). Does not fall out of the
continuity changes automatically - the subshell stack is repl control flow
and unwinds at pipe-EOF under the current nested model. Options recorded:
re-enter captured subshell stack on restart (fights nesting) vs the natural
fit under G-002 non-nested subshells with console targeting (reattach
reopened console to innermost active subshell). Also noted: a -subshell
flag on the shell subcommand as the primary entry (G-032 launcher-args
candidate).
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
User identified the general least-surprise violation beyond the original
error-retention draft: `'set ::jjj blah' | punkexe` reaches an interactive
prompt where ::jjj does not exist - the piped-EOF restart silently swaps in
a fresh codethread/code interp, discarding variables, procs, packages, cwd
and errorInfo. Goal reworked to session continuity via the caller-driven
restart identified during G-036 (repl::start eof-restart done-mode without
codethread teardown; app-punkshell restarts on the reopened console without
repl::init). Error inspectability becomes an acceptance criterion that
likely falls out free (no re-init means no boot-noise re-stamping of
errorInfo); the standalone error-record mechanism is demoted to a recorded
fallback. Detail file renamed to match (slug change, ID preserved).
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
Motivating transcript: piped `error xxxx` then interactive `set errorInfo`
shows tcllib virtchannel boot noise (caught `unset timer`) instead - the
restart boundary discards run-1's code interp, and bare ::errorInfo is
clobbered by internal caught errors anyway. Detail file records the two
mechanisms and design points (capture at the repl error-reporting site,
tsv/exitinfo handover, punk-owned record + one-line first-prompt notice,
quiet on clean pipes).
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
The version-mismatch and missing-header warning branches interpolated the
literal [X.Y.Z] inside double-quoted puts strings, so Tcl attempted command
substitution and the check died with `invalid command name "X.Y.Z"` the
first time a warning branch actually fired (surfaced by a manual
projectversion check during the 0.4.2 bump, whose CHANGELOG entry was
missing at the time). Brackets now backslash-escaped. Layout copies of
make.tcl synced by the project build included.
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
Motivating case: the tcludp 1.0.13 upgrade for G-036 - libs, vfscommonupdate
and project all completed while every kit vfs still bundled udp 1.0.12,
requiring manual copies into each vfs lib_tcl9 folder.
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
Live CloseHandle breakpoint (WinDbgX conditional bp on the sockListLock
handle value) caught the closer: Tcl thread-exit-handler walk in a dying
Thread-extension worker, tail-calling CloseHandle. The tcludp fossil diff
1.0.12 -> current names it: 1.0.12 Windows UDP_ExitProc ("called at thread
exit") closes the process-global waitForSock and sockListLock events, so the
first udp-loaded thread to die destroys the lock for every other udp-loaded
thread. Recycled handle values turn subsequent INFINITE waits into permanent
blocks (unrecycled values fail fast - why standalone probes stayed green
while punkshell run-2 startup churn wedged 4/4). Upstream already fixed in
1.0.13/trunk (UdpThreadExitProc per-thread + ExitSockets at process exit).
Remedy: upgrade bundled tcludp to 1.0.13+; loose ends recorded (punksys 8.6
udp version check, residual trunk weaknesses as optional upstream tickets).
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
Instrumented traffic-enabled specimen: wedged workers blocked (not spinning)
in WaitForSingleObject(sockListLock, INFINITE) inside tcludp event-source
procs (disassembly maps both wait sites to the sockListLock static; the
SocketThread released properly and parked on waitForSock). Handle-table data
from the full dump proves both tcludp global event objects were CloseHandle`d
mid-session: the statics still hold handle values now recycled to an
IoCompletion object and a manual-reset event (tcludp only creates auto-reset
events). Waiters starve forever on unsignalable objects. Only ExitSockets
closes these handles; the sole udp-loaded thread that died mid-session (run-1
shellfilter-run worker, terminated in the run transition) is the prime
trigger suspect. Console dependence dissolved - the CONIN$ restart was simply
the only mid-session udp-thread-death scenario. Minimal-repro die-variants
(release / terminate-mimic / full punk env) do not yet reproduce; next
candidates recorded (resultvar-terminate, thread::cancel, live CloseHandle
breakpoint).
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
