New punk::args::formcheck <id> ?-return dict|summary?: reports the form pairs
of a multiform definition that some argument list could cleanly match
simultaneously (the multipleformmatches inputs). Static pairwise pass over the
resolved FORMS enumerates each form's positional word-slot chains (leaders then
values; -optional and ?-wrapped clause-member branching; -multiple capped;
options excluded - order-free), screens aligned equal-length chains per
position (discriminator words via choiceword_match, type witnesses from a
small table), and CONFIRMS every candidate witness arglist with a real
single-form parse against both forms (parse_status - no raise, no
user-supplied words, no define/resolve cost). Findings are therefore witnessed
- discriminated form pairs cannot false-alarm; misses (exotic types,
option-requiring forms, enumeration caps) are the documented conservative
direction. Classes: type_weakness (discriminator aligned with a permissive
non-validating type - any/none/string/ansistring/globstring/expr/script) vs
structural (forms genuinely share an argument shape).
New @form key -overlapallowed <formname-list> sanctions a KNOWN overlap on
either pair member: the finding reports with sanctioned 1 and leaves the
result's unsanctioned list (the actionable/gate subset). Parse behaviour is
never affected; unknown form names are rejected at definition resolve
(end-of-forms cycle). @form directive doc updated.
tclcore moduledoc 0.3.4: the documented after cancelid/cancelscript overlap
(runtime-liveness ambiguity, 0.3.0 record) sanctioned on the cancelid form -
::after now reports zero unsanctioned findings while 'after cancel <id-shaped>'
still raises multipleformmatches. ::lseq deliberately unsanctioned: formcheck
reports range/start_count (witness {1 count 1}) AND range/count (witness
{1 by 1}) - both real, both rooted in the expr-typed end slot, kept visible
pending an expr syntax-validating type (G-069/G-070).
Tests: new args/formcheck.test (7) - no-finding cases (parse withid/withdef
pair, afterish/sharedform fixtures), class+sanction fixture, unknown-form
rejection, -return summary, ::lseq/::after pins with witnesses re-verified,
sanction parse-neutrality. punk::args suite 210/210, punk::ns 57/57.
G-074 achieved and archived (acceptance review in the detail file); G-055
verification gate gains the formcheck step (unsanctioned must be empty for
regenerated multiform commands).
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
Proposed goal, wording user-approved 2026-07-13: make the perl/python/node -e
reflex work on punk kits (top-level and script subcommand forms) instead of
erroring, without ever reproducing stock-tclsh argv-swallow/stdin misparse
behaviour. Companion to the tclsh -e guardrails commit (AGENTS.md entry +
claude deny hook).
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
Acceptance reviewed clause-by-clause in the detail file: auto-selection
on a unique clean match (forms.test GAPs flipped), candidate-naming
noformmatch/multipleformmatches errors, -form list restriction across
get_dict/parse/parse_status/arg_error, doc surface presenting the
best-matching form(s) ('i after cancel <id>' presents the cancel form;
's after cancel someid' underlines the matching synopsis lines),
explicit single -form unchanged, full punk::args/punk::ns suites pass
(full tree 822/836 with only the exec-14.3 baseline failure).
Flip edits: index entry to GOALS-archive.md (achieved 2026-07-13),
detail Status flipped with acceptance review and live-verification
record, reference sweep updates G-044 (candidacy API now available -
parse_status formstatus), G-055 backlink, G-072 backlink. Detail-file
move to goals/archive/ follows as a pure rename; goals_lint transiently
unclean between the two commits.
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
User-approved draft from the 8.6-vs-9 string is dict forward-compat
requirement: a new definition key (candidate -choiceunavailable) for
choices that are recognised but not available in the current runtime -
displayed among the choices with their -choicelabels notes, participating
in prefix disambiguation via the shared choiceword_match resolver (so
abbreviations colliding with forward-version choices are ambiguous
everywhere), and rejected at parse with a tailored recognised-but-
unavailable message. Adoption by the tclcore string is model gives 8.6
users the dict class annotated and reserved (deliberately stricter than
real 8.6 for the di prefix - recorded as a user-sanctioned parity
exemption; full-word behaviour stays parity-true), plus an
i-string-is-dict documentation id generated from the static description.
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
Space-form docid prefix parity: cmd_traverse's space-delimited child
docid jump, on an exact-word miss, now resolves the word against the
current level's choices-bearing first leader via
punk::args::choiceword_match (the shared G-040 resolver - -choiceprefix,
-nocase, -choicealiases, denylist, reservelist honoured) and retries
with the canonical word. 'i string is tr' resolves to the
"::tcl::string::is true" documentation exactly when 'string is tr 1'
executes; 'string is bool' -> boolean; ambiguous ('d'), unknown ('zz')
and denied words stay at the parent exactly when parse rejects them.
resolvedargs records the canonical, mirroring parse normalization. No
second matching rule exists.
Truthful cmdtype: cmdinfo classifies cmdwhich-notfound + non-empty docid
as 'doconly' (was 'notfound') - documentation-only levels below real
commands (per-class ids like "::tcl::string::is true", documented TclOO
method docids; the method case adopts doconly per the recorded design
decision, refinable by G-052). Consumers audited: cmdhelp/synopsis/eg
are docid-driven, cmdtrace tests only for 'proc', punk::help topic
fallback uses cmdwhich; punk::lib script analysis updated in step
(doconly accepted alongside notfound, bucketing unchanged).
Tests: the four G-051 GAP pins flipped and renamed
(cmdhelp_pseudo_command_cmdtype_doconly,
cmdhelp_spaceform_docid_prefix_honoured + ambiguous/unknown guard,
cmdhelp_string_is_true_pseudo_doconly,
cmdhelp_string_is_prefix_honoured). punk::ns 53/53 (cmdflow + non-GAP
cmdhelp unchanged), punk::args 193 pass / 1 pre-existing skip,
punk::lib 35/35; full source-tree suite result in the detail file.
Live verification (punk902z src): 'i string is tr' renders
byte-identical to 'i string is true' except the failure banner echoing
the typed words.
Flip edits: G-051 index entry to GOALS-archive.md (achieved 2026-07-13),
detail Status flipped with acceptance review and verification record,
reference sweep updates G-052 Notes. Detail-file move to goals/archive/
follows as a pure rename; goals_lint transiently unclean between the two
commits.
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
Root cause: get_dict_can_assign_value blanket-satisfied the member check
for any argument carrying choices, so an optional restricted-choice value
(the lseq '..'/'to' noise word) consumed any word whenever arity
permitted, starving later elements/clauses and failing validation with a
confusing trailing-choices error ('lseq 0 10 2' shape).
Fix: an allocation choice screen using choiceword_match (the shared G-040
implementation - exact/alias/prefix/nocase semantics; -choicemultiple
words screened per list member within min/max), applied only where
allocation has an alternative: -optional arguments and further
occurrences of -multiple arguments. Required arguments are deliberately
not screened - the word must fill them and validation's choiceviolation
reporting stays informative (the existing parsestatus/cmdhelp/choices
pins forced and now document both refinements). -choicerestricted 0
behaviour unchanged.
Results: the allocation.test GAPs flipped ('1 2 3' and '1 2 by 3' parse
with correct clause shapes {{} 3}/{by 3}; '1 2 3 4' gets the plain
excess-values rejection instead of blaming the unrelated optional);
prefix normalization survives the screen; all noise-word variants and
if-shape guards unchanged. lseq moduledoc matrix parses per lseq.n under
-form range, and 'i lseq 0 10 2' works end-to-end. Remaining lseq
divergences trace to G-041 form selection or the -type expr laxity
recorded in G-055 - not allocation.
Also corrected an increment-1 mis-premise: parse_status ALREADY accepts
-form before the withid/withdef tail per its documented synopsis - the
probe had passed it trailing. GAP replaced by
parsestatus_form_option_order (correct-order acceptance incl. the form
key, trailing rejection). No code change was needed for that acceptance
clause.
Verification: punk::args suite 193 pass / 1 pre-existing skip / 0 fail;
punk::ns 53/53; full source-tree suite 813 pass / 13 skip / 1 fail =
exec-14.3 only (known baseline) - zero regressions (tclsh 9.0.3; lseq
verification in punk902z src, Tcl 9.0.2).
Flip edits: G-071 index entry moved to GOALS-archive.md (achieved
2026-07-12), detail Status flipped with the acceptance review and
before/after record; reference sweep updates G-041 (prerequisite fixed,
parse_status correction) and G-072 Notes. The detail-file move to
goals/archive/ follows as a pure rename; goals_lint transiently unclean
between the two commits.
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
G-071 flipped proposed -> active (user direction 2026-07-12).
New allocation.test (7 tests) with reduced fixtures isolating the failing
shape from the tclcore moduledoc: the lseq-range shape (start ?sep? end
?by-step clause?) reproduces the moduledoc failures exactly. Current
mis-allocation pinned as GAP tests ("1 2 3" -> invalid blaming sep,
"1 2 by 3" -> incomplete blaming end, "1 2 3 4" correctly invalid but
misblaming sep), noise-word variants and the if-shape noise-word clauses
pinned as regression guards, parse_status -form absence pinned as GAP.
Also silenced four more unconditional debug puts on get_dict allocation
retreat paths ((111)/(222)/(333)/(444)) - these printed to stderr during
NORMAL successful parses at every optional-skip retreat, polluting
interactive help/parse output for noise-word-modelled commands. Behaviour
unchanged; the retreat logic they marked is exactly this goal fix target.
Full punk::args suite 193 pass / 1 pre-existing skip / 0 fail (tclsh
9.0.3).
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
Both user-approved drafts from the G-041 prework probe findings:
- G-071: value-allocation correctness for optional standalone values +
trailing optional-member clauses (the lseq "0 10 2" in-form failure),
error-blame quality, and parse_status -form support. A G-041
prerequisite: no lseq form accepts those arglists under the current
allocator, so form auto-selection alone cannot fix them.
- G-072: named compound clause types with per-alternate element typing
and arity for heterogeneous repeating clauses (try on/trap handlers),
building on the design sketches embedded in the ::try moduledoc notes.
Includes a recorded examination of Elixir gradual set-theoretic types
(user direction): punk::args -type | and literal() are already a
fragment of the set algebra; negation would subsume reserved-word
deny-lists; per-alternate arity falls out of union-of-shapes.
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
Both user-approved drafts arising from the G-045 tclparser assessment:
- G-069: dev-time lint cross-checking punk::args record-splitter boundaries
against tclparser parse command where the binary is available -
dialect-aware comparison (-& pre-join, ANSI strip), capability-gated,
zero new runtime dependencies for punk::args.
- G-070: pure-Tcl implementation of the tclparser parse-command API scoped
to what punk::lib consumes, parity-verified against the C library over a
probe corpus; replaces the tclparser_tcl error stub with
prefer-C/fallback-pure dispatch. Reference source to be user-provided
under TEMP_REFERENCE with recorded provenance.
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
Increment 5 (final): the container quoting rules pinned by defquoting.test
now appear in the punk::args::define -help documentation - braced values
fully literal (backslash sequences survive as typed); double-quoted values
get Tcl backslash semantics at record parse while $ and [] stay literal
with no substitution outside tstr placeholders; the backslash-escaped
placeholder idiom renders a literal placeholder. Rendered section verified
in punk902z src (meta-escapes display correctly). punk::args suite 186
pass / 1 pre-existing skip / 0 fail.
Acceptance review recorded in the detail file: all criteria satisfied
across increments 1-5 (@cmd -unindentedfields 0.6.1, i help alignment
punk 0.2.4, -& record continuation 0.7.0, @normalize + define_docs
consumer proof 0.8.0/punk 0.2.5, quoting documentation 0.8.1; suite grown
128 -> 187 tests, GAPs flipped, none weakened, full source-tree suite zero
regressions).
Flip edits: G-045 index entry moved to GOALS-archive.md (achieved
2026-07-12), detail file Status flipped with evidence in Progress,
reference sweep updates G-053 notes. The detail file move to
goals/archive/ follows in the next commit as a pure rename (per the
goals/AGENTS.md archive rules) - goals_lint is transiently unclean between
the two.
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
arg_error's cmd-help display transform (undent " "+help, max 4 - the
'#unindentedfields ?' todo site) is now gated by "-help" membership in the
@cmd line's -unindentedfields list, mirroring the existing per-argument
gate. The single transform site feeds both the table and string renderers,
so left-margin-authored @cmd help renders its first line flush with
continuations in both. @cmd -summary carries no indent transform in any
renderer, so -unindentedfields for -summary is vacuously honoured. No
in-tree definitions set -unindentedfields on @cmd - existing rendering is
unchanged. define doc for -unindentedfields now states where the option is
valid.
Tests: rendering_unindentedfields_cmd_help_GAP flipped to
rendering_unindentedfields_cmd_help (aligned expectation, both renderers
measured). Full punk::args suite 175 pass / 1 pre-existing skip / 0 fail;
punk::ns suite 53/53 (arg_error consumer); make.tcl modules builds clean
(tclsh 9.0.3).
Also: G-045 flipped proposed -> active (user direction 2026-07-12);
progress and remaining-work recorded in the detail file.
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
An interactive shell orphaned by its hosting console dying (killed
conhost/terminal) previously spun ~2 cores forever: the Tcl 9 windows
console driver never delivers the dead-console state to the script as a
fileevent (tclWinConsole.c ConsoleEventProc only notifies on buffered
data) while its reader thread busy-loops on the persistent channel error,
so the script level is completely blind and nothing ever closes the
channel.
Fix: repl::console_watchdog - a self-rescheduling liveness poll (default
5s, repl::console_watchdog_ms; read-only GetConsoleMode probe via
chan configure -inputmode) armed by repl::start only for a tcl9 console
input channel serving the process-default console on windows. On probe
failure it closes the input channel (stopping the driver's reader
thread) and finishes the repl via the normal eof done-path; app-punkshell
then finds no console reopenable and exits cleanly. Piped, foreign-console
and tcl 8.6 inputs never arm it. repl::start's post-vwait reader
deregistration now tolerates a watchdog-closed channel.
Verification (2026-07-12): kill procedure post-fix exits the orphan in
1.5-2.0s with no traceback (src mode and rebuilt kits punkbi/punk91/
punk902z); 25s live-console soak shows no spurious trigger, CPU delta 0;
piped stdin unaffected; repl consolebackends 3/3 and punk::console suites
88 pass / 1 skip; root cause verified against plain tclsh 9.0.3.
Upstream ticket filed: https://core.tcl-lang.org/tcl/tktview/f10d91c2d3
Included:
- goals: G-039 flipped achieved 2026-07-12 and archived (index entry to
GOALS-archive.md, detail file to goals/archive/ with full root-cause,
repro and verification record); reference sweep adds the eof done-value
producer note to G-038
- src/modules/punk/AGENTS.md: watchdog contract documented
- project version 0.12.1 -> 0.12.2 + CHANGELOG entry
- vfs payload sync: _vfscommon.vfs punk/repl 0.4.0 -> 0.5.0
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
New goals (user-approved drafts, all proposed) covering the declarative
vendoring direction:
- G-065 declarative vendoring: toml-declared external packages with
version/commit pinning, retrieval provenance, binary-scan gating with
punkproject.toml override; manual drop-ins stay supported (surfaced as
undeclared); agent-free by design
- G-066 pkgIndex.tcl-to-.tm repackaging: lib.copyasmodule expansion with
embedded LICENSE/metadata datafile and distribution-unit tracking for
multi-package upstreams (tcllib-style)
- G-067 module artifact channel: publish/retrieve prepared .tm modules
against configurable artifact servers, sharing the G-006 consent-gating
and source-override pattern
- G-068 agent-assisted moduledoc generation workflow for vendored
third-party libraries (G-055 pattern generalized), decoupled from basic
vendoring
G-063 contract extended (user-approved): vendored-package license
indications additionally carry verification provenance (method, verifier,
date), reported by the audit surface.
Proving case recorded in G-065 notes: the hand-trimmed tcl_oauth2_library
copy was load-tested then removed before ever being committed, so the
first vendoring of it runs end-to-end through the declaration; the
TEMP_REFERENCE clone remains the upstream stand-in.
goals_lint: clean.
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
Finalises the G-062 achieved flip staged by the prior session (punkshell
0.12.1): LICENSE.txt (BSD-2-Clause, Julian Marcel Noble 2023-2026) at the
repo root, README/punkproject.toml/AGENTS.md license declarations, index
record to GOALS-archive.md and detail file to goals/archive/.
Archive-loss prevention, from the G-015 incident (its achieved-status
verification parenthetical was silently dropped by the 2026-07-11 two-tier
restructure's Status-line normalisation; the text is restored to the G-015
archive file's Notes with provenance):
- root AGENTS.md 'Doc Restructures': deleted-line conservation check before
committing bulk doc migrations, structured-field-normalisation hazard
(relocate prose to body sections first), moves separated from edits
- goals/AGENTS.md: lintable header field grammar (one line per field, bare
Status values), flip-time verification evidence recorded in the body, the
archive move content-identical, and a new archive-time reference sweep:
pending-tense mentions of the archived goal updated in the live tier, and
actionable archived notes pointed to from the affected live goal's Notes
- GOALS.md maintenance rules: achieved-flip clause extended to require the
evidence write-up and the reference sweep
Retroactive reference sweep over all 12 archived goals (25 live detail
files): pending-tense fixes (G-002 G-008 G-013 G-016 G-017 G-021 G-022
G-031 G-042 G-044 G-050 - G-017's Goal/Acceptance annotated as
gate-satisfied, contract meaning unchanged), forward pointers pushed from
archived notes (G-062 license-seeding follow-on -> G-012/G-027, G-037
vendorlib/vfs drift semantics -> G-024, G-058 static-baseline mechanism ->
G-005), and one 'Archived-goal references' Notes bullet per remaining
referencing file so every live mention of an archived goal is resolvable
without consulting the archive index.
scriptlib/developer/goals_lint.tcl (new, plain tclsh): validates detail-file
header grammar, strict status values in both tiers, orphan rules in both
directions, Status/Scope mirror consistency, plus an informational (never
fatal) warning for live files referencing an archived goal with no
achieved/archive marker - baseline now zero warnings. Root AGENTS.md
scriptlib/developer ownership note widened to cover developer utilities.
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
Acceptance verified (consolebackends.test child-process drivers): repls run
interactively through ssh-socket and tk-widget ::opunk::Console subclasses
with size/at_eof/can_respond answered by the overrides, base class and
punk::console unchanged. Detail file records increment 2 and the non-gating
residue (per-run output batching, punk/0-only junction wiring, raw-mode
untested on foreign consoles, process-global console state -> G-008).
Project version 0.10.3 -> 0.11.0 with changelog entry (new user-visible
shell capability: repl::init -console).
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
G-062: canonical project license - root BSD-2-Clause LICENSE.txt with
SPDX-identified references in README.md, root AGENTS.md and a
machine-readable license field in punkproject.toml.
G-063: per-package license tracking - SPDX-normalized Meta license
indications via a friendly-name mapping module (authors need not know
SPDX ids), copyleft/viral-license flagging audit surface, and fixing
the literal %license% template placeholder seeding.
G-064: dev lib.search machine-parsable returns - ansi-free -return
dict/json with documented structure (G-049 pattern) plus an option
surfacing per-package license indications in table and machine returns.
All three proposed with user-approved wording (2026-07-11).
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
- src/tests/AGENTS.md: agent-added tests carry a one-line provenance comment `#added <YYYY-MM-DD> (agent[, G-<id>])[ - <short note>]` - immutable facts only (never "G-NNN will flip this" expectations, which live in _GAP_ test names and goal files); user-added tests optional; no bulk retrofit of existing suites. Rationale: provenance must survive where VCS history does not travel - packaged test modules (G-029), git+fossil dual history, file regeneration/moves
- GOALS.md maintenance rules: marking a goal superseded/abandoned includes a test sweep - grep G-<old id> (at minimum src/tests) plus the tests named in the goal's detail-file Acceptance, and record each test's disposition (transfers to the superseding goal / stands down to plain characterization / lapses) in the appropriate detail file; the sweep never deletes, skips, or weakens tests on its own
- the provenance lines are what keep the supersession sweep's grep reliable over time; closes the dangling-GAP-pin risk analyzed for superseded goals
- no project version bump: governance docs only
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
- GOALS.md collapsed to summary entries (ID/status/title/Scope/detail pointer): 104.6KB -> 23KB so a full read stays cheap; Scope lines kept verbatim so path-grep goal discovery still works
- canonicality split: index canonical for ID/status/title/Scope, detail file canonical for Goal:/Acceptance:; all 61 detail-file headers reconciled from the index (fixes stale copies, e.g. G-036 detail acceptance predated the achieved rework), bodies preserved untouched
- detail files created for the three index-only goals G-017, G-034, G-054; every goal now has one
- 10 achieved goals (G-007 G-015 G-036 G-037 G-040 G-046 G-049 G-054 G-058 G-059) archived: summary records appended to GOALS-archive.md, detail files moved to goals/archive/; archive-on-flip replaces the ~30-achieved-entries trigger
- GOALS.md preamble/rules reworked: read workflow (read index in full, then detail files of scope-intersecting goals before editing), contract spans both tiers with proposal-first unchanged, next-free-ID counts the archive, achieved flip judged against the detail-file Acceptance and includes archiving
- progress convention codified from G-001 increment-1 practice: index entries carry status only, never progress; incremental progress lives in the detail file's ## Progress section (landed/remaining); achieved flip requires the remaining-work list resolved - a partial increment never flips a goal
- goals/AGENTS.md rewritten for the split (required 4-field header, one detail file per goal, orphan rules covering archive/); root AGENTS.md Child DOX Index + Repo-wide Notes updated; GOALS-archive.md preamble updated
- stale detail-file paths updated to goals/archive/ in src/lib/app-punkscript/punkscript.tcl (comment), runtimebash_wsl.test, wslprobe.tcl and the G-042 detail file; propagated copies (root lib/, src/vfs/_vfscommon.vfs, src/_build) left to refresh via normal build steps
- no project version bump: governance docs and source comments only, no user-visible shell behaviour
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
- three new backend modules under src/modules/opunk/console/, base ::opunk::Console and punk::console UNCHANGED (the G-001 acceptance constraint - verified diff-clean):
* opunk::console::test / ::opunk::TestConsole - deterministic channel-pair test double: fixed size via -columns/-rows, is_console_or_tty/can_respond 1 (settled value wins), at_eof = plain chan eof with NO probe (pending bytes never consumed - pinned). The console seam identified by the G-044 repl characterization work
* opunk::console::ssh / ::opunk::SshConsole - socket-carried terminal sessions: construction-time capability (detection is the wrong tool - per goal detail), chan-eof without byte-consuming probes, size via the registered ANSI size-query provider over the connection. Flagship test: a scripted remote terminal answers CSI 6n over a socket pair and size resolves 100x30 through punk::console machinery querying the socket
* opunk::console::tk / ::opunk::TkConsole - Tk text widget as terminal: widget path in the inherited in/out slots (documented non-channel reuse), terminal_class tk-text, size from widget char dims, at_eof via backend marker (opunk::console::tk::set_eof) or widget destruction; no Tk require at module load. Verified live under punk91 src (the tk-loading experiment kit)
- voo -extends subclassing pattern recorded in opunk/AGENTS.md: children inherit public accessors + field INDEX variables (not parent-private my.* accessors) - constructors initialise inherited private fields via index vars, method bodies use parent public accessor methods; virtual dispatch via the slot-0 tag needs no base changes
- tests: modules/opunk/console backends.test (8 tests: dispatch, spec_resolve acceptance of subclass values, probe-free eof, settled-capability precedence, ssh capability/eof/size-over-socket/settled-0-no-emission, tk gated behind env PUNK_TEST_TK=1) - 7 green + tk skip on tcl 9.0.3 and 8.7; tk case verified standalone under punk91
- goal detail records progress + remaining work (repl -console launch wiring, output-channel parameterization, interactive acceptance verification); goal stays active
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
- the ::tcl::string::is definition harvests its class set at define time from the bad-class error message of a deliberately invalid probe (safe, side-effect-free) - accept/reject parity with the loading interpreter by construction: 8.6.13 = 21 classes (no dict - the previous static 9.0 list wrongly ACCEPTED string is dict there), 8.7a6 = 23 (+dict +unicode), 9.0.3 = 22 (unicode removed). Fallback to the 9.0 set if the message format ever changes
- hand-written man-page descriptions (kept verbatim, tstr-processed as before so the A_WARN highlights are unchanged) apply only to classes the runtime accepts; accepted-but-undescribed future classes get a generic label; static version notes added to dict (not in 8.6) and the new unicode entry (unreleased 8.7 only - removed in tcl 9). The per-class virtual docids (::tcl::string::is <class>) follow the harvested set automatically
- new tclcoreparity.test (4 tests, gated on have_tclcoredocs): choices equal the live-harvested set and every documented choice is really accepted; per-class docids exist for every class; error-vs-ok outcome agrees between real string is and parse_status across the 23-shape probe matrix (missing args, trailing flag-like str, option/class prefixes + ambiguity, unknown option/class, -failindex var consumption, per-version dict/unicode presence, divergent-classification shapes); version-note labels conditional on presence. Expectations derived from the LIVE interpreter, never version arithmetic - green on 9.0.3, 8.7a6 and (via a direct tcltest driver, since runtests infrastructure does not run under the plain 8.6 kit) 8.6.13
- full punk/args + punk/ns trees green (219 pass + 1 pre-existing skip) incl the have_tclcoredocs cmdhelp pins
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
- G-016 goal+acceptance: -return option (default table unchanged; dict = canonical machine form with documented per-checkout records incl the VCS field; json = faithful rendering for out-of-process consumers, round-trips the dict data)
- G-017 acceptance: the documented agent invocation standardizes on -return json as the parse target with its record fields (replaces the vaguer "expected output shape")
- G-016 detail records the design decisions: dict-first assembly (table rendered from it), suggested record shape, json via tcllib json::write, markdown deliberately not offered as a machine form (json for parsing, table for humans)
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
- 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 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
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
