- ConPTY (windows) + pty (unix) expect-like harness: spawn a built punkshell on a size-controlled pseudo-terminal, send keys incl control/arrow sequences, await patterns in the rendered ANSI byte stream with timeouts and forced teardown, full transcript capture
- the durable byte-accurate tier of the repl verification model recorded in goals/G-044 detail: pure layer (commandcomplete.test, done), console-seam unit tier (G-001 as enabling refactor), rendered tiers (G-020 screen capture near-term windows bridge; this goal headless + cross-platform)
- first verification targets = preserve-list behaviours: the in-proc {set x "{*}{"} continuation-hint sequence, raw-mode tab-marker rendering/deletion, up-arrow recall + edit of a multiline history entry
- detail file records open implementation questions (driving ConPTY from tcl: twapi surface vs helper exe; harness/shell synchronisation incl the inter-subshell beep-protocol idea vs prompt sentinels) and the G-059 WSL / G-060 QEMU-guest execution extensions
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
- new commandcomplete.test (6 tests, green 9.0.3 + 8.7): punk::lib::system::incomplete pure-function characterization - the info-complete quoting quirk (a quoted word with unbalanced braces e.g set x "{*}{" is complete standalone but needs extra closers inside a proc body; the pending-opener stack { " { " shrinks per typed closer), single openers, tabs in open braces, escapes, and an incomplete<->info-complete parity property over a case battery
- goals/G-044 detail: the user-specified preserve-list any repl refactor must honour (info-complete parity + quirk, closing-prompt hints incl the accepted single-candidate limitation pinned-not-fixed, raw-mode colour staging in-progress vs submitted, literal tab acceptance with raw-mode marker edit smarts, dim space dots display-only never leaking into submitted strings/history, up/down navigation of MULTILINE editbuf history with recalled entries editable) + testability findings: class_editbuf is console-coupled at its core (add_chunk renders via overtype::renderline against live terminal metrics - cursor-position size probing, DECRQPSR tabstops) so items 3-6 are not unit-characterizable until a console seam exists - G-001 (pluggable console backends / ::opunk::Console test double) is the enabling refactor, not just a feature goal
- goals/G-020 detail: repl interactive-behaviour verification recorded as a driving use case (near-term windows harness: keystroke injection + capture) pending the durable pseudoconsole expect-alternative
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
- new src/tests/testsupport/wslprobe.tcl (::punktest::wsl): memoized capability probe for the wsllinux constraint - default distro launches and unames as Linux, tools present (bash/mktemp/wslpath + sha1 tool), native tempdir file round trip; any failure -> skip with reason, so wsl.exe-present-but-unusable installs cannot false-positive. Staging helpers (staging_create/copy_in/run_in/cleanup) enforce the design: execution on the distro NATIVE filesystem only, shared /mnt used for one-way copy-in/out, the windows checkout never operated on from inside WSL (DrvFs slowness + cross-boundary stat differences that make git re-hash its index and fossil see phantom changes). Probe uses wsl -e invocations only (wsl --status/-l emit UTF-16)
- multishell.test: scriptwrap_multishell_exec_wsl_sh - the polyglot sh payload produces its marker under the distro bash from native staging (the direct isunix twin still skips on windows)
- new shell/testsuites/binscripts/runtimebash_wsl.test (8 tests): runtime.bash first-ever execution on real unix - multi-candidate run errors listing candidates, use/list/run round trip with argument passing, PUNK_ACTIVE_RUNTIME override, unknown/unselectable use errors, stale-active guidance, single-candidate fallback, offline list -remote (crafted cached sha1sums.txt + PUNKBIN_URL forced fetch failure), and the checkout-untouched guard (git status --porcelain identical before/after per acceptance)
- green on tcl 9.0.3 + 8.7 against Ubuntu-24.04/WSL2; suites skip cleanly when the probe fails; enablement/limitations in src/tests/AGENTS.md (known limitation: a present-but-HANGING wsl can stall the probe)
- GOALS.md G-059 flipped to achieved 2026-07-11; detail file records the outcome incl the UTF-16 discovery and the 512-byte label regression this work surfaced (caught by the guardrail suite as designed)
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
- G-059: capability-probed WSL constraint for driving unix-side tests from Windows (multishell sh-payload execution, runtime.bash behaviour). Native-filesystem execution is a design constraint: per-test artifacts staged into a WSL-native tempdir with one-way copy-in/out, no repo checkout inside WSL for these cases, future full-suite mode via a separate native clone - the Windows checkout is never operated on via /mnt (DrvFs slowness + cross-boundary stat differences force git index re-hashing and fossil phantom changes; two VCS clients must not share a working tree). Acceptance includes verifying the Windows checkout git/fossil state is untouched by a WSL-gated run.
- G-060: QEMU guests as strictly external tooling behind a hypervisor-agnostic guest-driving contract (provision/stage/run/collect, push-based - same pattern as G-059; guests never share a working tree with the host). GPL-safe posture recorded: external-process invocation only, no QEMU binaries or derived code in punkshell or punkbin, guest OS images not redistributed - fetched/built per machine. First target FreeBSD x86_64; config home deferred to the buildsuites toml direction.
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
- punk_main.tcl captures the runtime static baseline at kit boot: empty-filename [info loaded] prefixes probe-loaded in a throwaway interp (configurable denylist tk*/vfs/mk4tcl/vlerq/tdbc* for side-effecting/composite inits), recording only packages a load actually PROVIDES (diff on provides, not package names - probe loads can trigger index scans) into ::punkboot::static_packages/static_prefixes; the boot interp is seeded with ifneeded {load {} <prefix>} mappings
- punk::lib interp_sync_package_paths/snapshot_package_paths propagate the baseline and seed fabricated interps/threads; punk::repl codethread init (new %staticprefixes%/%staticpackages% scriptmap) and shellthread worker init do the same - the repl code interp on a static runtime resolves Thread again (punk91 = tclsfe-x64 + punk9win.vfs failed with "can't find package Thread"; the appended vfs replaces the stub's //zipfs:/app mount taking its static pkgIndex files with it, and the tclsfe PostInit hook seeds per-interp auto_path only)
- punk::packagepreference static-vs-bundled policy: requiring a baseline package ensures the static mapping and triggers the package unknown scan BEFORE resolution so bundled copies register and the highest version wins (newer bundled reachable, static not masked by older bundled); static registrations excluded from the loaded-shared-object same-version pinning
- composite statics defer correctly: static twapi provides nothing under the probe (script layer lived in the replaced stub zip) so the bundled complete twapi is the resolution; punk91 vfs/vfs::zip warning re-diagnosed as kit content (tclsfe bundles no tclvfs) - recorded in the goal detail, not a seeding defect
- tests: staticseed.test (4) + staticpolicy.test (4) un-gated simulated-baseline units (green 9.0.3 + 8.7); staticruntime.test (4) kit integration behind the capability-probed statickitavailable constraint (probes ::punkboot baseline incl Thread; env PUNK_STATICKIT_TEST_EXE override, default bin/punk91.exe) - 4/4 against the rebuilt punk91; punk902z/full shell tree/full source-tree suite baselines unchanged (exec-14.3 only)
- verification runtime tclsfe-x64.exe pinned in the punkbin artifact repo (separate repo, commit b2dbbe6) with sha1sums + new AGENTS.md scaffolding
- punkshell 0.6.0: CHANGELOG entry; AGENTS updates (src/vfs capture contract, tests indexes incl new punk/lib + punk/packagepreference entries, shell staticruntime contract)
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
- diagnosis from the punk91 tk-loading experiment (tclsfe-x64 + punk9win.vfs): plain tclsfe stub worker threads resolve static Thread 3.0.5 fine, but punkshell boot replaces package search paths wholesale and discards the runtime seeding - the repl code interp cannot find Thread ("failed to load punk::console"); punk902z unaffected only because its vfs bundles a thread dll
- fix shape: capture the static baseline (empty-filename info loaded entries + versions) before path replacement, seed fabricated interps/threads with 'load {} <pkg>' ifneeded scripts, and make punk::packagepreference resolve static-vs-bundled by a documented version-aware policy (punk91 loaded the OLDER bundled twapi 5.0.2 dll over the newer static Twapi)
- testing: un-gated unit tests against simulated baselines + kit-boot integration tests behind a capability-probed constraint (static-entries-incl-Thread kit present) - skips cleanly, extends to zig-era static runtimes (G-005)
- artifacts: verification runtimes (tclsfe-x64.exe at minimum) to be pinned in the punkbin artifact repo (win32-x86_64 + sha1sums.txt) so the constraint is satisfiable off this machine; .vfs folders already git-tracked
- detail file records probe evidence, the runtests-testinterp precedent (same bug class, directory flavour), the suspected quiet thread-over-builtin instance on punk902z, and the vfs/vfs::zip re-diagnosis follow-up
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
- default icon src/runtime/punk1.ico, per-kit override from the kit's .vfs; mechanism per tcl-sfe (TEMP_REFERENCE/tcl-sfe, Ashok P. Nadkarni): RT_ICON/RT_GROUP_ICON replacement via twapi resource-update APIs, ordered so the appended vfs payload stays intact (icon stub before append, or sfe-style split/update/reattach)
- detail file records the _vfscommon.vfs override-detection wrinkle (common punk1.ico merges into every built vfs - consult the custom pre-merge folder or an explicit mapvfs.config element), idempotence via delete-then-write, twapi/non-Windows skip path, and resource-inspection acceptance
- follow-on candidate flagged (detail file only): RT_VERSION stamping - copyright defaulting to the input runtime's own version-resource copyright, Product Name indicating the core Tcl version by default, both configurable via punkproject.toml and/or per-vfs config
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
- G-049 flipped to achieved 2026-07-10 (acceptance verified on Tcl 9.0.3 + 8.7); detail file records the shipped design, the incomplete-vs-invalid classification judgement call, and verification results
- G-054 [proposed]: ::tcl::string::is class choices harvested from the running interpreter at define time + cross-version behavioural parity pins (probing showed the static 9.0 list wrongly accepts dict on 8.6 - the real Tcl 8 target - and the hand model is otherwise behaviourally accurate incl the last-word-is-str C semantics)
- G-055 [proposed]: agent-driven tclcore moduledoc regeneration workflow - Tcl source tree + version as input (TEMP_REFERENCE/tcl9 interim; retrieval deferred to buildsuites toml/G-005 era), verbatim text policy with two exceptions (synopsis notation translated to punkshell syntax; line re-folding while punk::args lacks word wrapping), real-vs-model parity probe as the verification gate, provenance recording, modelability gap scan; proving set = whole ::string ensemble + selected others incl multi-form ::after; tkcore (shared-section reuse a la tk_standardoptions) and core.tcl-lang.org projects (tcludp) to follow later
- G-056 [proposed]: display-time word wrapping for punk::args help content (split-only never-join, ANSI/grapheme/double-width aware, paramindent-aligned continuations) - retires the G-055 folding exception for new work when shipped
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
Argument resolution no longer tstr-expands display-only content (-help on
@cmd/@examples/argument records, @formdisplay bodies): ${...} there is masked with
inert tokens (spec key DISPLAY_DEFERRED) and expanded at display time via
private::expand_display_fields (hooks in arg_error/eg/resolved_def/@default copyfrom;
separate display cache for non-dynamic defs; @dynamic re-expands per render preserving
provider refresh; reentrancy guard substitutes raw sources when expansion of the same
id re-enters). First parse of heavily documented commands drops accordingly
(punk::ansi::mark_columns first call ~4.3s -> ~12ms; tclcore ::lseq resolve
~184ms -> ~2ms) and -help content that calls punk::args-parsing commands - including
against its own definition id - resolves cleanly instead of stalling or looping.
-choicelabels stays eager (punk::ns reads it from parse specs in the subcommand walk).
Record splitter factored to private::split_definition_records.
Also per G-046 acceptance:
- @dynamic multiline -help substitutions align at the insertion column
(rendering_atdynamic_multiline_help_insertion GAP flipped)
- prefix/alias choice normalization keeps single-element-clause values plain-string
({\Deleted} list-wrap shape bug; choicegroups_imap_prefix_shape GAP flipped)
- -return string renderer aligns cmd-help continuations under the Description: label
(characterization updated) and its Example: line shows the example, not the doc url
- punk::ns cmdhelp shows plain info-scheme usage when no argument words are supplied
for a leader/value-requiring definition ('i string is', 'i punk::args::define') -
advisory parse runs -errorstyle minimal so the discarded error no longer renders a
second usage table (timing parity with pre-change: ~5.3s/4.1s on punk91 src)
Tests: deferredhelp.test (new); suites green on tcl903 + tcl87; full source-tree run
baseline-clean (exec-14.3 only). GOALS.md: G-046 -> achieved 2026-07-10 (activated
this session at user direction); design + verification evidence in the detail file.
Project 0.4.15.
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
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
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
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
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
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
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
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
Dump pipeline proven (procdump + WinDbgX scripted -z/-c/-logo). Uninstrumented
specimen stacks: workers indistinguishable wedged-vs-idle without heartbeat
timers (all in notifier MsgWait) - round 2 needs the instrumented build to map
wedged tids to dump threads. Structural finds: tcludp runs a global helper
thread (observed parked in WaitForSingleObjectEx inside tcl9udp1012.dll);
udp_tcl.c uses an auto-reset event as a pseudo-lock taken INFINITE in every
udp-owning thread's event-loop setup/check procs; checkProc recvfroms
non-blocking sockets per pass but does not decrement packetNum on the error
path (WSAECONNRESET from ICMP port-unreachable), while setupProc forces
zero block-time poll mode whenever packetNum>0 - a stuck packetNum locks the
owning thread's event loop into permanent poll mode. Blocking-recvfrom theory
ruled out (FIONBIO at open). Round-2 plan recorded (wedged-tid stack, MsgWait
timeout argument, per-thread CPU to discriminate spin vs block).
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
TEMP_REFERENCE checkouts confirmed current (Tcl core 2026-07-07, tcludp
2026-07-05). core-9-0-branch carries no tclWinConsole.c fix since 9.0.2, so
the wedge - if in the console driver - is likely still present upstream.
Current driver architecture recorded (process-global gConsoleLock, console
handle list shared across all Tcl threads, per-handle SRWLOCKs, reader/writer
threads with CONDITION_VARIABLE wakeups + Tcl_ThreadAlert fan-out) as the
credible wedge surface. Worker-side hypothesis sharpened: std-channel init on
a worker's first channel creation (udp_open / log-file open) attaches it to
the shared console machinery when the process stdin handle is the console -
fits which workers wedge vs survive, though probes have not yet reproduced.
Probe 'adopt' variant added (main thread closes stdin, CONIN$ adopted into
the stdin slot, SetStdHandle, active reader) - clean, ruling out the last
easy stdin-arrangement candidate. Approach reordered: native thread stacks
of a wedged in-context specimen promoted to step 1 (no debugger installed
yet - tool options noted).
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
Index entry recorded active per user. The detail file carries the full
investigation record: diagnosis chain of the piped-stdin exit/quit hang,
evidence and scoring caveats, ruled-out repro ingredients, remaining
candidates, and inline tooling listings (standalone probe script and the
hidden-console batch scorer with its 2026-07-08 baseline: punk902z run-2
syslog workers wedged 4/4, punksys 8.6 alive 4/4). Upstream reporting is the
user's manual step, gated on re-verifying against a Tcl 9 built from current
core sources.
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
New suite src/tests/modules/punk/libunknown/testsuites/shadowing/
(7 tests, all pass) pins the .tm same-version shadowing rules verified
experimentally 2026-07-06/07: tcl:™️:add PREPENDS each argument (last
arg ends at the head of tcl:™️:list); the head of tcl:™️:list wins
exact-version ties (single and separate add calls); a higher version
wins from any position (order only arbitrates exact ties); and
punk::libunknown preserves all of it (scanner parity). Shipped behaviour
depends on these rules - the runtests testinterp tm ordering (bootsupport
over vendormodules) and punk_main''s package-mode block precedence that
G-033''s proj:/kit-first design builds on - so a Tcl or libunknown change
that shifts the tie-break now goes red here instead of silently
mis-resolving.
Goal G-035 (proposed): characterise mixed .tm / pkgIndex.tcl provision of
the same package - same or differing versions, under standard package
unknown, punk::libunknown and punk::packagepreference, across
scan-trigger orderings, forget/re-require crossing forms, and 8.6/9.
Converts the standing informal rule ("avoid mixing provision forms for
one package - unexpected behaviour even with libunknown''s improvements")
from folklore into either substantiated AGENTS.md guidance with named
failure modes, or retirement if mixing proves predictable. Discovery
work, so goal-specified rather than written now; extends the shadowing
suite when implemented.
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
Design review outcomes (2026-07-07):
- Syntax: proj is not a fifth ordered token (category error - the dash
list is an ordered sequence of path blocks whose order IS the
same-version tie-break dial, per the verified tm rules and punk_main''s
own comment). Decided form: [proj:]<block>[-<block>...] - the prefix
scopes WHICH project root dev/src resolve against (cwd walk-up to the
nearest VCS repo root vs exe-relative), staying outside the ordered
list whose semantics are untouched. Explicit prefix = no silent rebind
on cd. Rejected: auto-detection, an explicit flag (less convenient),
token-attached qualifiers.
- Shadowing: visitor mode makes cross-lineage same-version-different-code
ties structurally expected (binary and visited project snapshots are
different vintages by definition). Order only arbitrates exact ties -
dev-versioned, higher-versioned and kit-absent modules come from the
project in either order. Canonical documented invocation is
proj:internal-src (kit-first: the visiting shell''s infrastructure
survives ties; for a standalone downloaded binary the kit is its only
trustworthy lineage and internal is location-independent); proj:src
documented as the faithful-vintage variant. Trimmed kits (G-019)
compose gracefully - kit-first only arbitrates ties.
- Required boot notice: detected root + effective precedence.
- packagemode help text drafted and persisted in the detail file as the
designated G-032 source (live only when the prefix ships); G-032 detail
cross-references it.
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
G-033: an explicit `proj` package-mode token lets an installed (visitor)
punkshell binary detect the punk project containing the cwd - walking up
to the nearest VCS repo root, the marker punk::repo::is_project_root
already uses - and set up source/dev library resolution against THAT
project, so `punkshell proj shell` explores a project interactively even
when the project builds no shell-capable binary (or no binary at all).
History check recorded: cwd project-structure detection was never active
in the boot modes (src/dev are exe-relative; os is shallow cwd-only), but
the runtime detector find_project already exists and dev commands use it -
so the marker question (VCS repo root, not punkproject.toml which tomlish
lacks) is already answered; this aligns boot modes with it. Explicit token
gates it per user decision (no silent rebind on cd); boot chicken-and-egg
(find_project is in punk::repo, not loadable at the package-mode phase)
handled by a lean inline VCS-root walk-up or post-boot deferral. Reuses
the existing src-mode path machinery, parameterised on the detected root.
Not gated on the module.templates/punk::cap plugin machinery.
G-034: zip-based #modpod modules (e.g. punk::mix::templates) fail to mount
in the shell subcommand's code interp on Tcl 8.6 - `dev module.templates`
errors with `invalid command name vfs::RegisterMount` / no template
providers - while the same call works via the script subcommand /
main interp (reproduced 2026-07-07). The code interp lacks the vfs::zip
library that supplies zip mounting for pre-zipfs Tcl. Tcl 9 (zipfs)
unaffected.
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
Root cause: Tk registers a main loop (Tcl_SetMainLoop); tclsh''s Tcl_Main
services it after the script, so `tclsh gui.tcl` behaves like wish. The
script subcommand sourced-then-exited, so a Tk script''s after-callbacks
never ran (scriptlib/tktimer.tcl flashed and died; shell was the
workaround). Confirmed: native tclsh tktimer 1 blocks ~1.35s; script did
0.38s.
Fix: after the script body (success paths only), if a Tk main loop is
registered (info exists ::tk_version && winfo exists .), tkwait window .
services the event loop until the main window closes, then exit - the
script-level equivalent of Tcl_Main. A script that exits from a callback
(tktimer countdown) terminates directly. Console scripts have no main
loop and exit at once; a script error exits at once (no hanging window).
Verified both generations: tktimer via script now blocks the countdown
(punk902z 1.49s, punksys 1.57s - Tk present in both) exit 0; tkhello_exit
immediate; tk-script-that-errors exit 1 in 0.37s (no hang); tkhello (no
self-close) blocks like wish; console script unaffected. Enables G-020
GUI automation via `script` instead of `shell` (noted in G-020 detail).
Project version 0.4.1.
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
New lean app package src/lib/app-punkscript behind the (previously stub)
script subcommand in punk_main.tcl:
- `<commands> | <punkexe> script` runs piped stdin to EOF - no trailing
exit needed; `<punkexe> script <file> ?args?` runs a file with
conventional ::argv0/::argv (bare non-subcommand first arg still
reclassifies to the file form). Script may itself read stdin in the
file form.
- Default punk shell environment via shared definitions (package punk
registers deck aliases e.g dev; punk::aliascore::init adds the utility
aliases) - no local alias lists, no boilerplate in piped one-liners.
- Honest exit codes: 0 success, 1 on error with errorInfo on stderr,
script''s own exit honoured. No shellfilter stacks/transforms, no
logging side effects, no interactive fallback (terminal stdin with no
scriptname is a usage error, never a blocking read or shell).
- Stdin form echoes the script''s final result when non-empty (one-shot
eval ergonomics: return-value commands like `dev projects.work <glob>`
emit their table without a puts wrapper); file form keeps pure script
semantics.
Verified on both generations (punk902z/tcl9 from _build - bin deploy was
file-locked; punksys/tcl8.6 from bin): piped success/error/exit-code,
file form with args and stdin passthrough, missing-file error, motivating
one-liner `dev projects.work *tomlish*` emitting the project table with
exit 0, `src` mode combination (dev modules load), and `shell` subcommand
regression smoke. G-015 flipped to achieved 2026-07-07 per GOALS.md
rules; goal detail records the verification and the manual console
spot-check item. Project version 0.3.0 (new user-visible shell
capability - minor bump).
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
Not a mode of app-punkshell. The acceptance is defined by absence (no
shellfilter stacks, no logging side effects, no interactive fallback),
which a package that never loads that machinery guarantees by
construction; app-punkshell''s load-time behaviour (shellfilter stacks
with syslog/file targets writing punkshell_*.log into the caller''s cwd,
logging threads) is wrong for one-shot calls; isolation caps the blast
radius of shell-path machinery. Duplication mitigation: the default punk
shell module/alias environment definition is factored into a shared
module-level definition (punk::aliascore as seed) consumed by both app
packages - share definitions via modules, not launcher control flow.
Package shape previews the G-031 registration model, as app-tomlish
demonstrated.
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
G-031: split the monolithic vfs main (punk_main.tcl: 1190-line apply
block - ~1060 lines boot machinery, ~100 lines dispatch tail) into a
layout-owned boot core (shipped via _vfscommon.vfs, sourced by
vfs-relative path since no package paths exist at boot; pull-updatable
per the G-027 ownership model) and a thin project-owned main declaring
app subcommands at commented customization points. Fork cost measured:
tomlish_main.tcl carries ~20 custom lines on a stale 500-line 2025
vintage copy; project_main.tcl (901 lines) same at template vintage -
boot improvements never reach derived projects. Acceptance: behaviour
parity across dispatch cases and vfs types, project subcommand added by
editing only the thin main (tomlish the proving ground), boot core
versioned/reportable (G-025).
G-032: the default dispatch defines subcommands via punk::args - tabled
-help enumerating built-in and project-registered subcommands, parsed
options with tabled usage errors (script/G-015 or version-report/G-025
as first candidates), G-030 degradation rules (guarded require; parsing
falls back to switch semantics, help to a plain list; rendering degrades
independently). Parked decision: the silent unknown-arg->script
reclassification should stop swallowing typos (candidate rule:
reclassify only when the argument names an existing file).
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
G-030 (proposed): make.tcl - the first surface a developer sees - parses
subcommands/options via punk::args and showcases the tabled usage for
help and argument errors; every interactive y/n prompt gains a declared
flag equivalent (interactive stdin prompts as today; flag proceeds;
non-interactive stdin without the flag fails fast with usage instead of
hanging or half-aborting) so agents drive make.tcl with arguments rather
than piped y/n; punk::args joins the bootstrap-tracked staleness set.
Degradation is a hard requirement: boot stays self-contained and the
repair commands (check/bootsupport/modules) keep working with plain
fallback help when the bootsupport punk::args or the ANSI rendering
stack is stale/unavailable - this week''s stale-fileutil and
stale-textblock incidents are the cautionary tales.
G-015 detail: recorded the runx -tcl result-shape observation (dict keyed
{result stdout stderr}, no exitcode key unlike exec mode).
G-020 detail: stamped the 2026-07-07 decision - acceptance gates on a
full testable Windows system without requiring other platforms first.
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
Root AGENTS.md "Git Commit Conventions" renamed "Commit Conventions (any
VCS)": the Co-Authored-By/AI-attribution ban and the Assisted-by trailer
apply to git commits and fossil checkins alike (git parses trailers
structurally, fossil comments are free text - either way the trailer is
the last line of the message). Generated projects start fossil-only but
may adopt git; punkshell itself is git-primary today and could flip.
CLAUDE.md mirror section updated to match.
G-027 detail: documentation/goals ownership design input - layout-owned
child AGENTS.md docs ride the pull channel under the
unmodified-since-install classification; project-owned skeletons (thin
root AGENTS.md, GOALS.md, goals/AGENTS.md, empty GOALS-archive.md) are
seeded once and never pulled; commit conventions are part of the seed
(developer-changeable, VCS-neutral); layout-owned marker convention;
transitive chains inherit the parent''s modified docs as their baseline.
G-012 detail: AGENTS.md template payloads recorded as the same hazard
class as live .gitignore payloads - a template AGENTS.md under
src/project_layouts/ is binding DOX for agents walking the punkshell tree
though written for generated projects; needs the same inert storage +
materialize-at-generation treatment.
First field test: the tomlish project was seeded today with the thin root
AGENTS.md + CLAUDE.md + GOALS framework this design describes.
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
src/tests becomes the single source of truth for module test suites: a
punkcheck-tracked make.tcl step generates the packaged test::<modulename>
#modpod modules from src/tests/modules/<namespacepath>/testsuites,
ending hand-maintained parallel copies under src/modules/test/.
The packaged form is a distributable in its own right: a user who
downloads a built module can optionally download the matching
test::<modulename> and verify the module''s behaviour on their own
system - package require + RUN interface, or a wrapped executable''s
-app test - with no source tree or harness. Acceptance proves the
standalone consumer scenario (runs without the project source tree),
suite-result parity with src/tests/runtests.tcl, and byte-for-byte
data fidelity (crlf roundtrip fixtures).
Motivated by the tomlish dual-copy interim (its modpod testsuites were
ported to src/tests while the modpod remains the live test::tomlish
build source - tomlish checkins 20bd00dc, feedb6f0).
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
Motivated by a make.tcl project deploy failure ("could not delete target
binary") where the locker turned out to be 7-Zip inspecting the exe -
identifying it took several dead ends because Windows has no cheap
file-to-process reverse lookup (name matching and Process.Modules scans
both miss plain file handles; openfiles needs a pre-enabled global flag;
handle.exe is external and elevation-bound).
G-028: a punkboot::utils helper returns the locking processes via the
Windows Restart Manager API (the installers-grade answer to "who is
blocking this file"), with twapi or cffi required lazily at call time -
punkboot::utils stays pure Tcl per the bootsupport no-compiled-extensions
contract, and unavailability degrades to the existing message. make.tcl
kit deploy failures append the locker report when determinable. Recurring
customer: G-023 versioned/dev binaries rewritten every build.
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
Projects generated by dev project.new receive a layout snapshot that
drifts; the current remedy is a push from punkshell (project.new -force 1
-update 1). G-027: one command run inside the derived project pulls
make.tcl/build.tcl, bootsupport modules/libs and template payloads from
the originating punkshell project - .punkcheck records remain the
provenance basis, origin identity becomes durable to workdir moves (not
relative paths alone; projects.work discovery as re-locator), VCS
awareness on both ends (G-026 clean-checkout policy on the source,
uncommitted-local-modification detection on the target), and the
remote-pull question gets a recorded decision.
Detail file records the motivating incident (tomlish 2026-07-06: a stale
make.tcl whose bootsupport updater was disabled by the very drift it
needed to fix - broken bundled fileutil::traverse under Tcl 9) and the
constraint that the pull entrypoint must not depend on the freshness of
what it updates.
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
make.tcl vendorupdate now walks up from each vendor source path to the
nearest fossil and/or git root and warns (non-fatal, once per VCS root)
when the checkout is dirty - vendored artifacts built from uncommitted
source have no committed provenance. Silent for unversioned or missing
locations; dual git+fossil roots report each VCS separately. First real
run flagged 8 dirty source projects (the tomlish 1.1.7/1.1.8 incident -
vendored content whose source history ended at 1.1.6 - motivated this,
remedied upstream by tomlish checkin 37b71e82).
Goal G-026 (proposed) carries the enforcement follow-on: abort with
explicit override, warn-only as configured mode, shared coverage of
bootsupport_localupdate, and a recorded decision on the residual
staleness gap. Abort-by-default now would block routine work given the
dirty-project count.
Project version 0.2.5; vendorupdate doc note in src/AGENTS.md.
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
G-023: builds produce punk8|9-<major>-<minor>-<patch>.exe from the
punkproject.toml version plus punk8|9-dev.exe tracking the latest build;
plain punk8|9.exe created initially and replaced only by an explicit
release step. Disk growth tolerated for now; archival/deletion trigger
recorded as a later question.
G-024: src/runtime/mapvfs.config converted to toml parsed via tomlish -
explicit runtime/vfs/name/kittype mappings preserved, plus generative
scheme declarations so the G-023 versioned outputs are one succinct entry
rather than per-version lines. Entry-level validation errors; full
migration preferred over a deprecation window.
G-025: build stamps project version, runtime binary and vfs folder into
the kit; a version-report subcommand prints them machine-parseably, with
the same-named punk-module command as the single implementation (the
subcommand is a thin wrapper) so scripts get the report in-process. Report
keeps build stamp, live runtime facts and source-tree version distinct:
src-mode sessions report stamp and live versions separately when they
differ; unstamped contexts (tclsh src/make.tcl shell, plain tclsh with
punk modules) report stamp fields absent rather than fabricated.
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
Goal G-022: scriptable safe fossil move/rename in dev repo (all checkouts
repointed, no phantom central config-db entries, no dangling old repo db,
project-name renamable with project-code preserved), then rename this
project fossil repo shellspy -> punkshell through that mechanism via a
G-015 piped script call.
New tests src/tests/modules/punk/mix/testsuites/repo/fossilmove.test pin
current behaviour in a FOSSIL_HOME-isolated sandbox with an isolation
guard: the file-copy + fossil test-move-repository sequence repoints the
checkout but leaves the old db file on disk, a phantom repo: entry in the
central config-db, and a stale ckout: back-reference; file moves never
touch project-name. GAP-marked tests flip when G-022 lands.
shellrun 0.1.4: add missing package require punk::args - the 0.1.3
migration left run/runout/runerr/runx calling punk::args::parse without
requiring it, which broke shellrun in bare interps and made every
src/tests/runtests.tcl run fail at test-file invocation. Full suite now
back to baseline (523 tests: 508 pass, 14 skip, exec-14.3 known failure).
Project version 0.2.4 (changelog entry for the shellrun fix).
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
G-018: zig-built plain zip-based tclsh kits with no punk infrastructure
(Tcl 9 kit satisfies acceptance; 8.6 interim = plain non-kit builds, kits
when practical, non-gating). Notes record that wish executables are never
a build target - Tk ships as a loadable package.
G-019: dependency-scan-driven module trimming for punk executables via the
tclparser parse API (c-only library today; punk::lib pure-Tcl fallback is a
stub), with a declared-extras manifest for scan-invisible dynamic requires;
batteries-included builds preserved.
G-020: screen capture + input injection module with per-platform backends -
Windows first (treectrl loupe + twapi, all already shipped in punk9win kit);
X11 (Linux/FreeBSD) and macOS follow behind the same contract; Wayland-native
out of scope. Platform show-stopper assessment recorded in the detail file.
G-021: agent-drivable visual/UI verification - window match, snapshot to
PNG/base64, scripted interactions - through G-015 piped script calls, with
guidance to land alongside G-017. aloupe.tcl stays a standalone app.
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
