punkshell/goals/G-097-bin-utility-naming-sweep.md

G-097 bin utility naming sweep: punk- prefix for remaining punkshell-own tools

Status: active Scope: src/scriptapps/ + src/scriptapps/bin/ (bits, runtime, tclargs scriptset renames; selfsign experiment scripts), bin/ (regenerated wrapper twins + renamed experiment scripts, old names retired), src/tests/modules/punk/mix/testsuites/scriptwrap/ + src/tests/shell/testsuites/binscripts/ (roundtrip pins), bin/AGENTS.md + referencing docs Goal: the punkshell-own bin utilities beyond getzig - the bits, runtime and tclargs scriptsets and the selfsign experiment scripts - carry the punk- prefix per the naming policy recorded in bin/AGENTS.md (G-096), so a user who adds /bin to their PATH gets collision-resistant names, while external-tool wrappers (dtplite, sdx, kettle) and getpunk stay unprefixed. Acceptance: bin/ presents punk-bits, punk-runtime and punk-tclargs (wrapper twins where the polyglot system emits them) and punk- prefixed selfsign experiment scripts, with the old names removed; scriptset sources and _wrap.toml configs are renamed to match; the byte-roundtrip pins (scriptwrap multishell runtime roundtrip, binscripts suites as affected) and every doc/script reference to the old names are updated with the affected test suites passing; no behaviour changes ride along with the renames.

Context

Utilities in bin/ are on a plausible user PATH ("/bin"), so generic names like bits, runtime and tclargs are collidable. User decision 2026-07-20 (recorded with the policy statement in G-096, achieved 2026-07-20): punkshell-own utilities take a punk- prefix; wrappers for external tools (dtplite, sdx, kettle) stay unprefixed, as does getpunk (already specific, intended future cross-platform entry point). getzig itself is renamed within G-096; this goal sweeps the remainder at a suitable time (user 2026-07-20: the renames "can wait").

Current inventory (2026-07-20): bits and tclargs are wrapped scriptsets (sources in src/scriptapps/, e.g. bits.pl/bits.ps1/bits.sh + bits_wrap.toml; outputs bin/bits.cmd + twins), runtime's scriptset lives in src/scriptapps/bin/ (bin/runtime.cmd pinned byte-for-byte by the scriptwrap multishell roundtrip test; bin/AGENTS.md carries its fetch/selection contract), and the selfsign material is loose experiment scripts (bin/selfsign.ps1, selfsign1.ps1, selfsign_test1.{bat,ps1}, create-localmachine-selfsigned-cert.ps1 + exported cert).

Progress

• 2026-07-21: main sweep landed. runtime scriptset renamed (sources + toml + payload self-reference messages) and REWRAPPED -> bin/punk-runtime.cmd (checkfile clean; .ps1 twin regenerated as byte-copy). tclargs + bits sources/ tomls renamed; their bin artifacts moved BYTE-FAITHFULLY (git mv, no rewrap): the drift check found both carry pre-template-refresh wraps (477-byte delta = the current template's wmic-deprecation timestamp fix) - regeneration is a behaviour change and rides separately per this goal's contract; fresh twins (punk-bits.ps1/punk-tclargs.ps1) cut from the current .cmds; stale untracked bits.bat/bits.ps1/tclargs.ps1/runtime.ps1 removed. selfsign set renamed (src: SELFSIGN.PS1 case-normalized to punk-selfsign.ps1, wrap toml, cert-create script; bin: all four untracked experiment scripts; exported .cer left - not a script). Pins updated: runtimecmd_roundtrip/runtimecmd_checkfile (target + scriptset name), multishell.test comments, runtimebash_wsl.test (incl the FUNCTIONAL staged-filename sites: bash ./punk-runtime.bash + the solo-fixture cp). Docs: bin/AGENTS.md (examples, policy paragraph now records the sweep, runtime section header, stale pin pointer fixed to runtimecmd_roundtrip.test), src/scriptapps/AGENTS.md (same class), root AGENTS.md + README.md + src/README.md, untracked bin/runtime/README.md, G-060 reference, libunknown comment (src copy; the root modules/ + bootsupport copies catch up on their normal re-vendor cycles). Suites green: scriptwrap + binscripts 26 run / 25 passed / 1 constraint-skip / 0 failed (roundtrip pin passes against the renamed artifact; WSL payload behaviour tests pass).
• 2026-07-21 REMAINING - user decision needed (scope): the project LAYOUT stores (src/project_layouts/vendor/punk/project-0.1/bin + the modpod-templates equivalent) SHIP utility copies: runtime.cmd (stale 2025-era payload, 96k vs current 114k) and getzig.cmd (pre-G-096 name - that rename missed this channel). Generated projects therefore still receive old-named, stale utilities, and the layout's src/runtime/Readme.md references bin/runtime.cmd. Options: fold into this goal (rename + refresh to byte-copies of the current bin artifacts + Readme update; layout paths would join Scope), or defer to a layout-utility-sync mechanism. Both-or-neither per file: renaming the Readme reference without the shipped artifact would make layouts self-inconsistent.

Notes

• 2026-07-21 (user): SEQUENCING CONFIRMED - this goal runs FIRST, then G-103, then the 8.6 arc (G-099/G-100/G-101). Rationale: G-103 extends the runtime scriptset's list/use (metadata surfacing) - renaming runtime.cmd -> punk-runtime BEFORE that work means the roundtrip pin and bin/AGENTS.md contract are touched once, and the punk- utility namespace is settled before G-103's runtime-naming decision lands.
• bits background (user 2026-07-20): Windows Sandbox experiments for starting things on a clean machine. Windows Sandbox differs from a true fresh windows install but remains a reasonable initialization proving ground if automatable; qemu may be the better target for full cross-platform testing (G-060). bits is kept regardless of sweep timing.
• selfsign experiments likewise kept (user 2026-07-20); rename only, no productization implied by this goal.
• runtime.cmd has the widest blast radius: the scriptwrap roundtrip pin (src/tests/modules/punk/mix/testsuites/scriptwrap/multishell.test scriptwrap_runtime_cmd_roundtrip_no_drift), the bin/AGENTS.md runtime fetch/selection contract section, and runbook references - all updated as part of the rename.
• Related goals: G-096 (policy home + getzig rename), G-060 (qemu test matrix), G-089 (scriptlib/kit deployment surface).