The G-173 structured-renderer procs (path_conflicts_for_exe, path_entries,
path_render_text, path_render_json, and the punk::path dispatch tail) were
authored with \ line-continuation backslashes in proc bodies, violating
src/modules/AGENTS.md (debug line-number matching). Refactor every G-173
helper to the dict-create + dict-set accumulator and json::write
accumulator idioms so no proc body uses a trailing \. A stray continuation
introduced at line 6752 (return [punk::path_machine_return ...]) is replaced
with an lappend accumulator + expand. The user's doc-block edits convert the
punk::path punk::args::define block from \ continuations to -& record-
continuation markers with manually wrapped help text (table-width safe).
Add scriptlib/developer/linecont_lint.tcl, a linter that flags
\<newline> continuations outside punk::args doc blocks. It resolves a real
Tcl parser (the C tclparser library, or punk::lib's pure-Tcl punk::tclparser
fallback) and locates doc-block spans structurally (punk::args::define brace
arg, lappend PUNKARGS command range) so the exemption is not a regex guess;
comment-line trailing \ is also exempt. Sourceable linecont_lint_run proc
with a script-mode guard; run as a script it exits 0 clean / 1 findings / 2
usage. 5 pinning tests in runner/testsuites/parser/linecontlint.test cover
proc-body flagging, punk::args::define exemption, lappend PUNKARGS
exemption, comment-line exemption, and a clean expand-style proc (pass Tcl
9 + 8.6).
src/modules/AGENTS.md: the -& record-continuation marker is now REQUIRED for
new and edited punk::args doc blocks (existing blocks may keep \ until
touched; editing a \ block requires converting to -& in the same change);
the closeout trailing-\ search is cross-referenced to the linter.
Assisted-by: harness=pi; primary-model=huggingface/zai-org/GLM-5.2; api-location=huggingface.co
Activated per user direction; activated goal flipped proposed -> active (overlap
survey re-run at activation; new Related: G-016 - sibling json round-trip
consumer. G-042/G-019/G-061/G-110/G-167/G-171 deliberate non-overlap).
::punk::path gains three options:
- -return text|dict|json (default table, byte-unchanged): the structured modes
build an ordered entry list from the shared collect dicts
(d_path_info/d_bin_info/d_index_executables) and serialise without
ANSI/textblock. text is a fixed-key plain-ASCII layout; dict returns a Tcl
dict; json is emitted via tcllib json::write (the preferred encoder settled
by the runtests json_emit hardening) so booleans/counts are bare JSON
numbers/1-0 and the decoded form equals the dict form byte-for-byte.
- -context <namespace> (default the caller's namespace): makes the
TCL-context conflict verdict stable for a machine consumer invoked through
a wrapper.
- -conflicts 0|1 (default 1): skip conflict computation for a small perf win.
The table render is kept verbatim (byte-identical default output). The
structured modes use a clean exact|nocase conflict classification
(path_conflicts_for_exe) independent of the table render's ANSI path. A
duplicate-path entry now reports the original's exe_count with an empty
executables list (mirroring the table column).
PUNKARGS argdoc updated; new options documented (whatis -doc punk::path shows
the synopsis + per-option help + choices).
Tests: src/tests/modules/punk/pathcmd/testsuites/tests/pathcmd.test (7 tests:
dict shape, duplicate/overshadowed fields, json ansi-freeness + round-trip
parity, text ansi-freeness, -context stability, -conflicts 0, default-table
still ANSI). Passes on Tcl 9.0.5 and Tcl 8.6. Existing punk::path module tests
(path.test, 67) unchanged/green.
Versioning: punk module buildversion 0.2.8 -> 0.3.0 (minor - new user-visible
options on ::punk::path); punkproject.toml 0.57.1 -> 0.58.0 (minor - new
user-visible shell behaviour) + CHANGELOG entry. goals_lint clean;
projectversion OK.
Assisted-by: harness=pi; primary-model=zai-org/GLM-5.2; api-location=huggingface.co
Everything a bake EMITS is now keyed by the artifact's TARGET platform rather than the
driving tclsh's personality: the bin/runtime/<tier> store a runtime is read from, .exe
suffixing of runtime files and kit outputs, presence checks, and whether the pre-deploy
process sweep uses tasklist/taskkill or ps/kill. Host semantics - copy commands, path
handling, filesystem case rules, prompts - stay keyed to the host.
The default target is the host's platform canon EXCEPT for a cygwin-family host (an
msys2/cygwin-runtime tclsh, which reports tcl_platform(platform) unix on windows), which
targets win32-x86_64. Such a host now drives the identical kit set, names and store
addressing as a native tclsh; before, it reported every kit runtime=missing against a
nonexistent mingw64-x86_64 store.
mapvfs.config entries take an optional 4th element naming the kit's target platform, so a
runtime kept in another platform's tier is a first-class mapping entry. The linux tclkit
entry now declares linux-x86_64 and bakes to a suffixless bin/punkshell902.
Zip-type kits assemble without zipfs in the driving tcl: when tcl::zipfs::mkimg is absent
(any 8.6) the image is built by raw-runtime split + punk::zip::mkzip + concatenation - the
same helper the zipcat type uses. Both mount identically (archive-start-relative offsets).
Fixes exposed by the above: the runtime capability probe looked for a suffixless filename
and so reported find-fail for every runtime on windows; with real capabilities arriving,
the extraction try-list was found to test capability presence rather than value, which
would send a plain zipfs runtime down the kit path where a failed sdx mksplit replaces
raw_runtime with the un-split original; BUILDCOPY names now follow the runtime's own
filename; runtime map keys strip only .exe (file rootname would eat the last dotted
segment of tclsh9.0.5); and native windows command lines run through a guard suppressing
msys2's posix-path argument rewriting - without it taskkill /PID <n> reached taskkill as
taskkill C:/<msysroot>/PID <n>, so the sweep could find a running kit but never replace it.
punk::platform folds the msys2 family (mingw64/mingw32/ucrt64/clang*) onto one stable
'msys' tag and CYGWIN_NT onto 'cygwin' - msys2's uname renders that token from MSYSTEM,
so one binary otherwise canonizes differently per launching shell. New normalize_os;
cygwin-x86_64 added to the platform table; 'help platforms' documents the fold.
make.tcl check reports the derivation on one line; bakelist rows carry target=<platform>
for non-default targets and the detail block names the tier; workflow text gains key note
[K9]. New characterization suite maketclplatform.test (5 tests, two self-gating on
discovering and probing a real msys/cygwin tclsh). Full suite 1112 tests: 1093 passed,
18 skipped, 1 failed = the documented exec-14.3 baseline.
Verified: msys2 tclsh8.6 bakelist output identical to native Tcl 9; a changed punk91
baked and deployed from that host with the sweep killing a running instance msys ps
cannot see; a real cross-target linux kit baked from windows to a 24MB ELF; a zipfs-less
8.6 bake producing a bootable zip kit.
Assisted-by: harness=claude; primary-model=claude-opus-5[1m]; api-location=anthropic.com
- platform records + 'help platforms' gain buildsuite
(supported|planned|candidate|none): whether OUR zig buildsuites produce
runtimes for a platform. Deliberately a separate axis from tiers -
punkbin-structured repos (or third-party equivalents) can host runtimes
built by any mechanism, so runtime-tier hosting coexists with
buildsuite=none (netbsd/dragonflybsd-class examples, per user review).
openbsd/netbsd/dragonflybsd records now carry the runtime tier.
Current values: win32-x86_64 supported (suite_tcl90), linux-x86_64
planned (G-105), linux-arm64/linux-arm/macosx/freebsd-* candidate,
rest none.
- G-109 notes record the binary-.tm platform reality the user's fat-tm
experience established (retracting this survey's earlier
'tm-are-cross-platform' shorthand): multi-platform fat .tm are the
wrong shape (oversized downloads; same-version shadowing leaves no
drop-in path), platform segregation must ride tcl:™️:path via
per-platform TM ROOTS selected by boot - and platform dirs cannot nest
inside an existing tm root (subdirs are namespace components), so those
roots must be sibling trees. Candidate manifest field: declared target
platform so libunknown can skip wrong-platform binary .tm.
Project 0.18.1.
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
Survey outcome (punkbin vs punkshell platform folders): five naming sites
had drifted - punkbin folders, bin/runtime, vendorlib_tclX dirs, the
punkboot platform_generic snips (an old platform::generic copy), and the
Tcl platform package itself whose outputs vary by version (1.1.x renamed
modern macOS to 'macos', aarch64/amd64 pass through unmapped).
Canon: <os>-<cpu> punkshell platform-dir names, cpu normalized
amd64->x86_64 and aarch64->arm64 (arm = 32-bit; on macosx arm folds to
arm64 - Apple silicon is 64-bit only), os macos->macosx. The universal
'macosx' name is the runtime-tier convention (punkbin + bin/runtime keep
one macOS folder, per make.tcl's existing collapse); per-arch
macosx-x86_64/macosx-arm64 serve the lib tier.
- new module punk::platform 0.1.0: platforms (canonical records with
status supported/dormant/recognized + tiers), normalize, local
?-tier lib|runtime? - full PUNKARGS argdocs. Tcl's platform package
stays the raw identifier underneath.
- punk 0.2.7: 'help platforms' topic (alias 'platform'; all prefixes
mutually ambiguous so they fall through to command lookup, per the
env/environment precedent) - canon table with the local interpreter
marked and raw platform-package identifiers for comparison.
- boot: punkboot platform_punk (inline normalization copy, sync-comment
contract with the module) in punk_main.tcl/project_main.tcl/make.tcl;
all platform-dir call sites switched to it. make.tcl exercised live;
main.tcl copies brace-verified.
- vendorlib_tcl8/9 synchronized to canon: freebsd-amd64 -> freebsd-x86_64
(READMEs updated), freebsd-arm64/linux-arm64/macosx-arm64 added, tcl8's
untracked-empty linux-arm now tracked + tcl9 gains linux-arm, stray
untracked macosx-arm empties removed, msys-x86_64 marked dormant
pending a utility decision, top-level READMEs state the canon contract.
- punk-runtime bash prongs emit canonical names: aarch64 -> linux-arm64
(no fetch default until punkbin carries that folder), arch-aware
freebsd/openbsd/netbsd/dragonflybsd via normalized cpu tokens.
Rewrapped; roundtrip pin PASS; layout copy + .ps1 twin refreshed.
Flagged for user decisions (recorded in G-105 Notes): punkbin linux-arm
holds an arm64-named kit (recommend linux-arm64 folder at next arm
publish; artifacts immutable), msys-x86_64 disposition, optional
platform-1.1.x re-vendor, src/vfs stays mapvfs-categorized (recommend a
mapvfs platform column when cross-wraps land, not a .vfs tree
restructure). Project 0.18.0.
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
New goal G-076 (active): adopt the upstream tcl9 dead-console fix (ticket
f10d91c2d3, root-caused in G-039) via a single version gate shared by the
'help tcl' warning and the repl watchdog arming.
- punk::lib 0.4.3: has_tclbug_console_deadspin + pure classifier
tclbug_console_deadspin_applies, gate variable
check::tclbug_console_deadspin_fixed_in (empty = all Tcl 9 windows
runtimes affected). Buginfo dicts gain a mitigated/mitigation axis
orthogonal to level; the deadspin check reports mitigated when
punk::repl >= 0.5.0 is available to the runtime.
- punk::repl 0.5.1: repl::start arms the dead-console watchdog only when
the check reports the runtime affected - recording a verified fixed
release once flips both consumers.
- punk 0.2.6: 'help tcl' renders mitigated warnings subdued (term-grey)
with a "(mitigated)" annotation and the mitigation text; severity
classification unchanged.
- checkbugs.test: classifier truth table, live-check consistency, and
mitigated-axis validation in the generic every-check sweep.
The fixed_in flip is deliberately deferred until a released Tcl passes
the G-039 kill-procedure re-verification (watchdog disabled, clean
script-visible eof exit) - recorded as the goal's remaining acceptance
item.
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
New bare @normalize directive: opts a definition into indent normalization
of BLOCK-FORM multi-line field values (first line whitespace-only, as
authored by opening a braced literal with a newline). The structural first
newline and a whitespace-only trailing line are dropped, the content
lines' common leading whitespace is the block's base indent, the first
content line is unindented fully and subsequent lines are re-based to the
standard 4-space continuation convention (deeper relative indents
preserved; whitespace-only inner lines become empty). Fields in a record's
-unindentedfields are exempt. Implemented as a resolve pre-pass over the
split records (private::normalize_records / rebase_multiline_value);
@normalize with options is an error.
Head-form values are never altered - their base indent is unknowable
(continuations uniformly at 6 may be base-4 with the deliberate +2
relative convention, or base-6 flush; re-basing would flatten the former).
The idempotence test caught exactly that on a file-style definition during
implementation, narrowing the user-confirmed re-base semantics to block
form only - which also makes @normalize a proven no-op on conforming
file-style definitions.
Consumer proof (punk 0.2.5, per the recorded user decision):
::punk::helptopic::define_docs converts from interim left-margin authoring
to indented block-form values under @normalize, dropping its
-unindentedfields declarations; 'i help' and 'i help_chunks' verified
aligned in punk902z src, including the blank-line separator in the
combined basehelp+extra block.
Tests: new normalize.test (5 tests: block re-base, block left-margin,
head-form boundary, exemption byte-exactness, file-style idempotence);
rendering.test P4 characterization stays pinned as the deliberate unopted
default with its text updated to reference @normalize. punk::args suite
186 pass / 1 pre-existing skip / 0 fail; punk::ns 53/53; full source-tree
suite 806 pass / 13 skip / 1 fail = exec-14.3 only (known baseline) - zero
regressions (tclsh 9.0.3). define doc documents the directive.
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
::punk::helptopic::define_docs now authors its help text at the left
margin and declares -unindentedfields {-help} on the generated @cmd line
(honoured as of punk::args 0.6.1, increment 1) and on the topic argument
line (a gate that existed all along but was never applied here).
Previously: the @cmd -help braced literal carried ~16 spaces of source
indent into the constructed definition (constructed defs get no
whole-block normalization, pinned P4 characterization), so the
Description block rendered continuations +12 right of the first line;
the \n-relative topic -help rendered its first line +4 (the injected
display prefix). Both blocks now render flush. Help text content
unchanged (manual ~70-col folding retained).
Verified in punk902z src (arg_error render + i help end-to-end);
punk::ns suite 53/53; make.tcl modules builds clean. Planning note
recorded in the goal detail file: the constructed-def normalization
increment picks its consumer proof (define_docs re-conversion vs
ensemble_subcommands_definition) when it lands.
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
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
- 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
