Engine-primitive pins landed green ahead of activating the launcher
definition/documentation/help-depth goals (args subtree 321 tests: 318 pass,
3 known-bug skips, 0 fail on native tclsh90 9.0.3 and tcl87):
- forms.test: candidacy fencing/fall-through group (G-168 pre-work) -
regexprefail-fenced autoselection fixture pin (args-tier twin of the G-150
cmdhelp.test pins), a -regexprefail rejection on an OPTIONAL value slot is
form-fatal with NO re-landing on later permissive slots (contrast
optional-choice rejection), unknown-option / dangling-option /
option-satisfied-but-values-unmet failures fall through to sibling forms as
successful parses, option-VALUE fences participate in candidacy, and the
documented per-word limit: a complete '-encoding <name> <file>' line
double-matches a fenced scriptfile form vs a dash-tolerant stdin form
(stock's scriptfile-wins-when-complete priority is not expressible
per-word - multipleformmatches per the G-041 contract).
- formviability.test: dangling-OPTIONAL-option verdict conservatism - the
G-164 re-probe re-seats only words naming missing REQUIRED options, so the
tclsh '-encoding' dangling class stays invalid although completable.
- errorselection.test: a dangling optional value-taking option word seats as
a trailing value and overflows a zero-value window as plain
toomanyarguments (no -badarg attribution).
- formcheck.test: GAP before-state pins of the punkexe launch definitions -
unsanctioned structural overlaps for script file/oneliner and tclsh
scriptfile/stdin, and every primary launch line double-matching; flipped
deliberately when G-168 lands per its Acceptance.
- docpackages.test (new): registered-namespace lazy definition loading
characterization (G-169 pre-work) - inert registration with scan-vs-load
split, id_exists never triggers loading, real_id/usage lazily resolve
tag-prefixed script-level id families, duplicate definers resolve
last-loaded-wins with only a stderr undefine notice (the engine's recorded
detect-duplicates todo), degraded paths clean.
Goal notes (non-contract): pre-test findings recorded in G-168 (including the
'-e'-must-be-a-required-flag declaration constraint and the residual-overlap
design limit) and G-169 (handover must withdraw the moduledoc entry in the
same change-set - no duplicate warning surface exists); G-170<->G-151
Related: cross-links added both ways - the dry-run arm renders G-151's
punk::args-level landing report, a link the path-based overlap surveys could
not surface. src/tests/modules AGENTS.md punk/args bullet extended for the
new coverage. goals_lint clean (84 active, 86 archived).
Claude-Session: https://claude.ai/code/session_0156PuejSCGjgeGb7jiABrDU
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
Three [proposed] goals from the 2026-08-05 formhint-arc discussion of
why launcher help stops at the subject word:
G-168 selection-sound launch definitions - script/tclsh forms made
parse-discriminable with EXISTING vocabulary (file form -regexprefail
{^-e$} + oneliner '-e' element; tclsh scriptfile-vs-stdin via
candidacy fall-through matching stock semantics). Corrects the
discussion's earlier assumption that G-072 negation was required:
-regexprefail participates in form matching (G-143-arc verified; the
G-150 hash declaration is the dash-led precedent). Includes the
dispatch parse-gating decision (tabled vs app-plain errors, latency
measured if adopted).
G-169 app-owned launch-subcommand documentation - app-punkscript owns
(script)::punkexe::script via inert registration, launcher resolves
lazily (the existing argsid/package/docpackages machinery), single
definer per id, ownership rule recorded (app-owned for app-handled,
moduledoc for core-owned like tclsh), and the *_main.tcl declaration
surface (summary/package/argsid/parse) documented as the official
authoring mechanism.
G-170 launcher help depth - 'help <sub> <formname|index>' narrowing
(G-150 usage -form precedent), make.tcl-style dry-run gated on
parse-trueness (G-168 built-ins, project parse=1) with the
prepend-help idiom preserved for passthrough subcommands, and the
punkexe 0.6.1 interim -formhint suppression flipped to real
' <punkexe> help <sub> %formname%' templates.
Follow-on handling (user-approved leans): G-144's override-set
follow-on flipped => goal G-168 (the make.tcl half landed in the
G-143 arc; the punkexe-moduledoc half is now G-168's recorded
decision); G-150's selection-soundness sweep follow-on stays open
(broader than these two definitions - G-168's Notes record the
partial enactment). Overlap survey per the authoring workflow:
G-089/G-055/G-072/G-075/G-042/G-043/G-044 relationships recorded in
the detail files; app-punkscript intersects no live goals.
goals_lint clean (84 active, 86 archived).
Claude-Session: https://claude.ai/code/session_01QgaxV27VZkmEec7oNbEVFc
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
The multi-form definitions (tool, buildsuite) each declare
'@cmd -formhint " make.tcl help <sub> %formname% …"', so
'make.tcl help tool' / 'help buildsuite' - and every dispatch usage
error for those subcommands - label each form's synopsis line with the
concrete dry-run-help invocation (' make.tcl help tool build ...'
rendered with U+2026) instead of the repl-oriented ' i -form N ...'
default, which is unreachable for (script) ids. Renders via the
promoted bootsupport punk::args 0.17.0; under older snapshots (e.g
generated projects) the key is ignored and the default labels render.
Design decisions (user direction 2026-08-05, recorded in the follow-on
disposition): the trailing ellipsis is required for honesty - help
DRY-RUNS the form's own command line after the action (G-143), so a
hint without it misrepresents the invocation as complete. The template
was kept over empty-string suppression because the labels also render
on dispatch usage errors ('make.tcl tool frobnicate'), where the user
never typed help and the hint is the discovery route to per-action
help; suppression would lose that teaching path.
maketclhelp.test: tool formhints pin flipped to the new labels with an
olddefaulthint-absent guard; buildsuite multiform test gains the same
pair; header + provenance comments updated. The ellipsis is matched as
its utf-8 byte triple (format %c%c%c 0xe2 0x80 0xa6) because
maketcl_run reads the child pipe -translation binary, so multibyte
chars arrive byte-wise - a real U+2026 char in the pattern can never
match (first-cut pin failed green-render for exactly this). 12/12
green on tclsh90; maketcltool.test 4/4.
Sync outputs batched per policy (make.tcl modules + bootsupport): the
basic + project-0.1 layout make.tcl copies, the modpod source-tree
copy, and the bootsupport templates-0.2.0.tm repack all carry the
identical +2-line change. The archived G-149 follow-on disposition
flipped => landed 2026-08-05 (the sanctioned same-work-unit edit);
goals_lint clean. punkshell 0.55.1 + CHANGELOG (make.tcl help output
is product surface - patch). Kits pick this up at the next
vfscommonupdate + bake.
Claude-Session: https://claude.ai/code/session_01QgaxV27VZkmEec7oNbEVFc
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
The per-form hint labels rendered beside a multi-form definition's
synopsis lines in the usage/arg_error table (hard-coded ' i -form N
...' previously) are now a template substituted per form: %formindex%
is replaced with the form's 0-based ordinal, %formname% with its name,
and an empty template suppresses the labels entirely (the cell keeps
just the Synopsis: label, as single-form renders always have). Both
acceptance arms landed. Definition side: new '@cmd -formhint
<template>' key - rides the existing arbitrary-key cmd_info merge (no
resolver change), round-trips through resolved_def, not display
-deferred; documented in the define -help directive-options. Caller
side: new -formhint option on arg_error (manual parser + PUNKARGS
block) pulled into usage via its existing resolved_def opts pull;
supplied-empty (suppress) is distinct from not-supplied (the option
declares no -default, so an unsupplied usage call passes nothing
through). Precedence: caller > definition > built-in default, whose
template substitutes to the exact prior bytes. Motivation (G-143
origin): script-level (script) ids - make.tcl's - are unreachable from
any repl, so the repl-oriented 'i' hint was not actionable there.
Scope decisions pinned: single-form renders never carry hint labels;
the -return string renderer has no hint column and is unchanged.
Byte-identity for unconfigured definitions proven by pre/post capture
diff of 'punk::args::usage ::punk::args::parse' (identical bytes,
through the usage pass-through path). Tests: new formhint.test (9
tests - default labels, directive/caller/suppression matrix, parse
-error path, single-form + string-renderer scope); full punk/args
subtree 302/0-fail on BOTH tclsh90 9.0.3 and the punk86 kit (8.6);
punk/ns subtree 115/115 (cmdhelp consumer). make.tcl help untouched
until promotion (maketclhelp.test still pins the bootsupport hint).
Goals: G-149 activated at user direction then flipped achieved
2026-08-05 + archived (index record newest-first, detail file to
goals/archive with Progress evidence and 1 follow-on: make.tcl
adoption after a bootsupport promotion => open). Activation-freshness
survey recorded the G-167 relationship (same renderer surface -
composition note both sides); reference sweep updated G-151/G-167
mentions; goals_lint clean, no orphaned xref pairs. punkshell 0.55.0 +
CHANGELOG. Bootsupport/vfscommon snapshots unchanged until promotion +
bake.
Claude-Session: https://claude.ai/code/session_01QgaxV27VZkmEec7oNbEVFc
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
New proposed goal (user-approved wording, from the post-G-073 design
discussion 2026-08-05): version/context deltas of a command's interface
become declarable and honestly surfaced without delta computation,
layered by delta kind. An @form may be declared unavailable -
participating in candidacy/diagnosis, displayed annotated, tailored
formunavailable rejection when only unavailable forms match, silent
resolution to the available form when both match (the first sanctioned
exception to G-041's no-silent-preference rule: documentation never
competes with reality), -form selection displays but refuses parse.
Option NAMES may be declared unavailable (the G-073 mirror at the
option-name level) with pointed tailored rejection. The default render
stays on available forms plus an AUTOMATED note enumerating unavailable
shapes (name + authored note + navigation hint - no computed delta;
user display decision relaxing the strict G-073 display-among-peers
principle for shape deltas only, since named things keep per-name
display via the option/choice layers). formstatus gains an additive
'available' field (G-152 contract) as the machine surface, and
authoring guidance prescribes -choiceunavailable for subcommand-shaped
deltas so the same concept never surfaces through two inconsistent
paths.
Detail file records the layered-model rationale, the silent-preference
exception scope, the two-paths trap prescription, era authoring via
shared -form tags (one form per version era - linear), engine seams,
and the relations/overlap survey (G-073 foundation, G-166 sibling
surface, G-152/G-041/G-074/G-150/G-149/G-044/G-055). Acceptance and
the lsearch -stride adoption candidate are agent-derived for user
review; status proposed. goals_lint clean (82 active / 85 archived).
Claude-Session: https://claude.ai/code/session_01QgaxV27VZkmEec7oNbEVFc
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
New per-argument key -choiceunavailable <list>: names recognised but not
available in the current runtime/context. Entries display among the
choices under a dedicated "Unavailable (recognised, not selectable
here)" group (one rendering-side injection - both renderers,
choicelabels notes, choiceinfo markers, trie prefix marking and
value-in-effect exclusion all inherited) and join the prefix pools;
synopsis literals and goodchoice marking never include them. Resolve
-time validation: no collision with choices/alias names/reservelist,
-default may not be unavailable, requires -choices/-choicegroups.
choiceword_match gains an optional 8th argument and an 'unavailable'
result key (matched stays 0 - matched-only consumers unaffected):
exact, nocase and unique-prefix landings carry the name as canonical; a
prefix shared with an available choice stays plain-ambiguous.
Validation rejects a landing with the tailored PUNKARGS VALIDATION
{choiceunavailable <name> choices <list>} error (-badarg/-badval;
private::unavailable_choice_msg names the supplied word, the resolved
entry, its choicelabel note and the available values; shared by final
validation and both G-082 overflow raise sites via rejection kind
'unavailable' from the allocation screen). Ambiguity messages annotate
unavailable longer matches '(recognised but unavailable)';
-choicerestricted 0 keeps full passthrough.
tclcore 'string is' adoption: curated forward list {dict} ('unicode'
deliberately excluded) diffed against the define-time harvest; labels
and per-class virtual ids extend to unavailable classes. On Tcl 8.6:
dict displays with its "(class not present in Tcl 8.6)" note,
'string is dict' rejects informatively, 'string is di' is ambiguous
(deliberately stricter than real 8.6 - recorded as a user-sanctioned
parity exemption; full words parity-true), and 'i string is dict'
documents via the virtual id. punk::ns cmd_traverse passes the key at
both resolver sites (doc-walk parity; the choice-traverse comment now
documents the choice-resolution vs doc-addressing axes split). tclcore
moduledoc requires punk::args 0.16.0-.
Tests: new choiceunavailable.test (10 tests); usagemarking.test gains
the goodchoice-exclusion pin; tclcoreparity.test gains forward-class
adoption invariants and the sanctioned 'di' strictness exemption, with
the version_notes pin deliberately flipped (dict's label now renders on
every runtime). Green: the three suites 37/37 on native Tcl 8.6.10
(luck runtime), 8.7a6 and 9.0.3; punk/args subtree 293/290/3 skips/0
fail on 9.0.3 AND 8.7; modules/punk sweep green except the three
documented pre-existing box-baseline failures (grepstr x2, nslist x1);
ns cmdhelp/corp 58/58 after the comment clarification.
Goals: G-073 flipped achieved 2026-08-05 + archived (index record
moved, detail file to goals/archive with Progress/verification and 3
follow-ons). G-166 drafted [proposed] at user direction (approved
wording): cmdinfo availability key + cmdhelp marking + tclcore leading
note + prefix-landing decision; the enacted G-073 follow-on flipped
=> goal G-166, the G-055 pattern follow-on => goal G-055 with a Notes
pointer added there. goals_lint clean. punkshell 0.54.0 + CHANGELOG.
Bootsupport/vfscommon snapshots unchanged until promotion + bake.
Claude-Session: https://claude.ai/code/session_01QgaxV27VZkmEec7oNbEVFc
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
A REQUIRED typed value or leader whose present word fails the basic-type
allocation screen (int/double/bool/number/dict) now reports the pointed
typemismatch naming the word and argument (-badarg/-badval, same shape
as the G-082 overflow-site selection) instead of the generic
missingrequiredvalue/missingrequiredleader shortfall. The in-loop
required-arg raise sites consult the rejection record returned by
get_dict_can_assign_value; the leaders-loop edit mirrors the values
loop per the MAINTENANCE contract. Unchanged by design: end-of-input
shortages (valuemissing/count classes), literal-typed members,
multi-member clause partials (no rejection record - conservatism
preserved), and required-arg choice words (never screened - G-071
asymmetry, choiceviolation already pointed).
parse_status: the shape now classifies invalid/typemismatch (the
formstatus viability verdict was already invalid; one probe re-parse
saved); argdoc status-key note updated. Pins deliberately flipped:
parsestatus.test (renamed parsestatus_typed_value_screen_typemismatch),
formviability.test (single-form top-status/formstatus split demo
re-anchored on a required-option shape), punk/ns cmdhelp.test message
match. New errorselection.test coverage: required value + leader
typemismatch pins plus unchanged-shape guards.
Verified tcl 9.0.3: punk/args subtree 280 total / 277 passed / 3
intended skips / 0 failed; punk/ns only the pre-existing nslist(1)
box-baseline failure (stash-verified unrelated). tcl 8.7: touched args
suites 38/38, cmdhelp 45/45.
Follow-on disposition flipped => landed in
goals/archive/G-082-punkargs-error-selection.md (goals_lint clean;
ledger 23 open / 20 goal / 15 landed / 2 declined). punkshell 0.53.1 +
CHANGELOG entry. Bootsupport/vfscommon args copies stay 0.15.1 until
the next promotion + bake.
Claude-Session: https://claude.ai/code/session_01QgaxV27VZkmEec7oNbEVFc
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
The one manual residue on G-106 - interactive typing-experience
confirmation of raw mode where the pwsh consolemode fallback does the
mode flipping - is confirmed by the user on tclsh9.0.5-punk.exe (the
store-active twapi-less suite 9.0.5 runtime). Disposition flipped
open -> landed 2026-08-05.
Disposition-only edit per the goals/AGENTS.md Follow-ons contract.
goals_lint clean; goals_followons now 24 open / 20 goal / 14 landed /
2 declined.
Claude-Session: https://claude.ai/code/session_01Y1diJnhjUxKgEG6EwYAzxj
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
Evidence-checked continuation of the archive follow-on sweep:
- G-087 fauxlink link_as encoder => landed 2026-07-17: implemented in
fauxlink 0.2.0 (link_as + punk::args doc, upstream checkin 1e6b4ee8)
within the goal's own stage 2; the '=> open' marker derived from
Notes prose written earlier that same day, before stage 2 landed.
- G-139 linux-x86_64 lib-tier emission for punk9linux's tcllibc
siblings => goal G-140: G-140's delivered scope covers the item
exactly (tcllibc-tcl9-r1 emission, sibling replacement/supersede,
punkbin publication f94ffd2) and its record cites the G-139 flip
note as its origin.
Disposition-only edits per the goals/AGENTS.md Follow-ons contract.
goals_lint clean; goals_followons now 25 open / 20 goal / 13 landed /
2 declined (count also reflects c7470dac's G-165 mkimg-retirement
landing, committed independently of this pair).
Claude-Session: https://claude.ai/code/session_01Y1diJnhjUxKgEG6EwYAzxj
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
zipfs_wrap.tcl (renamed from zipfs_mkimg.tcl, same CLI contract): payload zip
written by the driving shell's builtin tcl::zipfs::mkzip - convention-stable
across mkimg vintages (probed 8.7a6 vs 9.0.3: identical member tables/CRCs) -
with the prefix executable concatenated OUTSIDE the writer, plus an EOCD
archive-relative self-check per wrap (exit 9 on file-relative output).
build905.zig wrap lane updated (3 call sites, identifiers zipwrap_*); suite
README states the wrap contract; G-165 follow-on disposition => landed.
Verified: standalone wraps under both vintages mount/boot identically (840
members, base=prefix); suite make-zipfs/smoke/kit-family green - all 5
products probe archive-relative and boot (family_check plain/punk/punk-bi,
tclsh90szip smoke, tclsh90sprzip manual boot).
Assisted-by: harness=opencode; primary-model=openrouter/moonshotai/kimi-k3; api-location=openrouter.ai
The G-159 retrofit recorded both of G-122's deferred items as '=> open',
but each had already been enacted by a drafted goal that cites G-122 as
its motivation:
- pure-Tcl zip decoder for the zipfs-less bake path => goal G-124
(punk::zip::unzip/members/archive_info, achieved 2026-07-26; make.tcl
extraction still consumes it and no zipfile::decode requirement
remains in the tree)
- refuse-to-deploy on missing tcl_library => goal G-125
(boot-precondition gate punkboot::utils::vfs_boot_library_report,
achieved 2026-07-27)
Disposition-only edit per the goals/AGENTS.md Follow-ons contract.
goals_lint clean; goals_followons report now 28 open / 19 goal /
11 landed / 2 declined.
Claude-Session: https://claude.ai/code/session_01Y1diJnhjUxKgEG6EwYAzxj
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
Every make.tcl zip-kit bake is to emit an ARCHIVE-relative kit regardless
of the driving interpreter's zipfs vintage (legacy file-relative mkimg in
8.7/9.0.0, fixed mkimg in 9.0.1+, or no mkimg at all): zip-kit assembly
moves to a single writer layer - punkzip (zig) when its binary is present,
punk::zip::mkzip (pure Tcl) as the always-available floor - with
tcl::zipfs::mkimg retired from the pipeline, and file-relative output only
via an explicit per-kit mapvfs.toml opt-in. Workstream order (user
decision): upstream punkzip root-strip/exclude enabling changes first,
then the punkshell seam. The detail file carries the driver-vintage probe
evidence (8.7a6=file, 9.0.3=archive), the upstream fix provenance (ticket
aaa84fbbc5, core 3d62ee540d 2024-12-05), the write-path benchmark (mkimg
11.4/35.9s vs mkzip 8.1/24.8s vs punkzip 6.7/20.0s at 132MB/396MB), the
drafting-time overlap survey and Related lines.
Assisted-by: harness=opencode; primary-model=openrouter/moonshotai/kimi-k3; api-location=openrouter.ai
The closing-banner prefix check 'string match "$line_inner*"' treated
the raw test name as a glob pattern, so a test NAME containing glob
metacharacters (* ? [ ] backslash) never matched its own opening text:
the closing banner failed to close the failure section and every later
event including the summary line was swallowed (the G-161 wedge class;
latent, unexercised in the corpus). The check is now an exact byte
prefix compare (string equal -length) - identical semantics for ordinary
names, and an empty line_inner keeps the historic match-everything
behaviour. New parsetestrun-globname-7.0/7.1 pins: 8/8 green tclsh90
single+multi-process and tclsh86, parser dir 10/10.
Landed directly at user direction from the archived G-161 Follow-ons -
disposition flipped to landed in the same change-set (the sanctioned
archived-file edit). runner/AGENTS.md parser coverage bullet updated.
CHANGELOG + punkproject 0.51.2.
Assisted-by: harness=opencode; primary-model=openrouter/moonshotai/kimi-k3; api-location=openrouter.ai
- new goal (user-drafted 2026-08-04): when the valmin reservation seats a word that literally names a declared required option into a required value slot and the resulting optionmissing stands in the G-152 viability probe, re-parse with the stolen word(s) consumed as the option they name; pure end-of-input exhaustion after that re-seating grants viable-incomplete. Runtime seating unchanged (the trailing-flag-as-value rule is load-bearing, pinned by flagvalues_plain_then_dash)
- surfaced by the G-150 batch + independent second-session review: 'i hash -t' classes the test form '(not viable)' although 'hash -t foo' is valid - a false negative, GAP-pinned in cmdhelp.test (owned by this goal; the pin flips at achievement)
- overlap survey in the detail file (G-044 consumer; G-152/G-150 archived relations; args/ns family anchors dismissed as unrelated mechanisms)
- G-044 Notes: records G-164 as the probe-layer answer to G-152's "completion consumer lookahead" note for the valmin-reservation class
- goals_lint clean (82 active, 82 archived)
Assisted-by: harness=opencode; primary-model=openrouter/moonshotai/kimi-k3; api-location=openrouter.ai
Acceptance met in full (evidence in the archived detail file's Progress): 'i ::punk::auto_exec::hash -r' renders only the rehash form's usage and '-d <name>' only the delete form, driven by the declaration (bare punk::args::parse withid selects flag-led forms uniquely via the show_or_set name's -regexprefail {^-}; no hash-handler involvement); runtime behaviour otherwise unchanged (dash-led name needs an explicit flag form - accepted cost); ensembles/single-form/no-word invocations render as today. The goal reduced to its declaration half - cmdhelp's G-041 advisory-parse candidacy already narrowed on a unique selection.
- index entry -> GOALS-archive.md; detail file -> goals/archive/ with Progress evidence and Follow-ons (handler multi-name -t missing-name defect => landed 2026-08-04 by user fix; selection-soundness sweep of other definitions => open)
- activation-freshness xref re-run at activation recorded; reference sweep at archive: no live-tier mentions, no xref bridges lost; goals_lint clean
- code/tests landed in the preceding commits (auto_exec 0.1.1, ns 0.9.2, cmdhelp.test 45/45); punkshell 0.51.0
Assisted-by: harness=opencode; primary-model=openrouter/moonshotai/kimi-k3; api-location=openrouter.ai
- known_renamers and debug are now info-exists guarded like the rest of the
module state (all_stacks, renamer_command_tokens, token_implementations) -
a module re-source refreshes proc definitions only, no longer resetting
them while stacks/tokens survive
- previously the reset stranded live stacks: the removal forms gate on
known_renamers membership, so surviving records' renamers became unknown
and removal errored
- contract documented in commandstack::help; pinned by
commandstack_reload_preserves_state
- suite 41/41 on tclsh90 (9.0.3) + punk86 (8.6); packagepreference consumer
suites 6/6 on both; minted modules/commandstack-0.7.1.tm
(bootsupport/vfscommon promotion left to the next cycle, as with 0.6.0/0.7.0)
Assisted-by: harness=opencode; primary-model=openrouter/moonshotai/kimi-k3; api-location=openrouter.ai
Acceptance met in full (evidence in the archived detail file's Progress): the named invocations punksys -e {puts hi} / punk902z script -e {puts hi} and the full matrix (piped and unpiped stdin, no-arg usage error on both surfaces, errorInfo + exit 1, argv0/argv, result echo, tclsh -e stock-parity boundary) verified by hand on the baked kits; scriptexec.test + launcherhelp.test 49/49 green. Index entry -> GOALS-archive.md, detail file -> goals/archive/ with Progress evidence and a (none) Follow-ons section; G-141/G-158 reference-sweep achieved markers; no xref bridges lost. goals_lint clean.
Assisted-by: harness=opencode; primary-model=openrouter/moonshotai/kimi-k3; api-location=openrouter.ai
- pop_rename renamer ?command? - pop the renamer's topmost stack entry and
return the removed record (searched across live stacks when no command
given; entries on multiple commands are an ambiguity error)
- remove_renamer renamer - remove ALL of a renamer's entries across every
live stack (the unload-my-package form); returns removed records keyed
by command
- restore_original command - unwind the whole stack to the original
implementation regardless of renamer; registers stack-evidenced renamers
into known_renamers so it is not gated by state loss (module re-source)
- all three route through remove_rename's re-linking/token-map machinery;
Rename_stack-parked stacks are invisible to the renamer-wide forms
- suite 40/40 on tclsh90 (9.0.3) + punk86 (8.6); packagepreference
consumer suites 6/6 on both; minted modules/commandstack-0.7.0.tm
(bootsupport/vfscommon promotion left to the next cycle, as with 0.6.0)
Assisted-by: harness=opencode; primary-model=opencode/kimi-k3; api-location=unknown
The '---- errorInfo: ' / '---- errorCode: ' prefixes are 16 characters;
parse_testrun captured from index 15, so every captured value led with
the prefix's trailing space. Capture now starts at index 16 -
report-shape normalization only (continuation errorInfo lines were
always raw and are unchanged). parsetestrun-multiline-error-3.0 pins the
normalized shape (errorcode exact, errorinfo anchored) instead of
trimming/tolerating; 6/6 green tclsh90 + native tclsh 8.6.
Landed directly at user direction from the archived G-161 Follow-ons -
disposition flipped to landed in the same change-set (the sanctioned
archived-file edit). CHANGELOG + punkproject 0.49.7.
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
Acceptance met in full (evidence in the archived detail file's Progress):
synthetic + e2e parser suites committed and green both runner modes and
both Tcl generations; full-suite parity PARITY ok in both modes;
src/tests/AGENTS.md relaxed to style guidance. Index entry ->
GOALS-archive.md, detail file -> goals/archive/ with Progress evidence
and three structured open Follow-ons (single-line banner anchoring,
glob-metachar closing-banner match, errorInfo/errorCode leading space).
Reference sweep: no pending-tense live-tier references existed;
goals_lint clean (83 active / 80 archived); goals_followons registers
the three open items; goals_xref reports no lost bridges.
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
User-directed activation (proposed -> active, index + detail mirror).
Activation-freshness survey (goals_xref score G-161) recorded in the detail
file Notes: no related live goals - every overlap pair is unlinked with zero
path intersection (lexical noise only; interval-drafted G-163 unrelated).
goals_lint clean.
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
New goal (user-approved wording): punkshell exit paths on unix ttys restore
blocking on the shared tty file description and drain pending stdout/stderr
(bounded best-effort) before teardown - closing the tclIO behaviour where
stdin's non-blocking read windows make stdout non-blocking underneath,
'flush' silently no-ops once a background flush is scheduled, and TclInExit
discards EAGAIN'd buffers (measured 2026-08-03: 161/5000 lines survive exit
on a throttled WSL pty; ~498KB pending after a 'successful' flush). Guard
homes in punk::console, invoked after the G-038 eof-restart decision point;
acceptance includes complete delivery under a slow reader, bounded exit under
a dead reader, unchanged windows/piped behaviour, ARCHITECTURE.md exit-section
documentation, and a unix-pty-gated pin. Related: G-038, G-013, G-011, G-090
(+ archived G-036 lineage).
goals_lint clean; overlap survey recorded in Notes.
Claude-Session: https://claude.ai/code/session_01QgaxV27VZkmEec7oNbEVFc
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
New goal (user-approved wording): 'make.tcl bakelist' gains per-kit payload/
runtime freshness verdicts answering "would a rebake change this kit?" without
baking - punkkit-stamp.toml schema 2 records content digests of each kit's
assembly inputs (payload vfs manifests via the assembler's existing per-entry
CRCs, runtime artifact digest, resolved mapvfs declaration, bake schema) and
bakelist compares them against the current tree. Verdicts degrade per kit to
'n/a (<reason>)' (pre-digest stamp, unreadable container, mk4 driver
unavailable) without aborting the listing; zip kits read pure-Tcl via
punk::zip, mk4 kits only where a metakit driver loads. Context records the
existing deployed column's real (narrower) role: deploy-hop integrity for the
locked-exe trap. Related: G-131, G-158, G-023, G-147, G-137.
goals_lint clean; overlap survey (goals_xref paths + score) recorded in Notes.
Claude-Session: https://claude.ai/code/session_01QgaxV27VZkmEec7oNbEVFc
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
tee_to_pipe declared the transchan 'clear' op; the Tcl core delivers 'clear'
before every write when declared (the G-145 defect class - see
goals/archive/G-145-piped-usage-ansi-remnants.md) and the handler discarded
o_encbuf, the held partial multi-byte character. The following chunk then began
with orphan continuation bytes and could never decode (the tail-backoff only
trims the end), so whole chunks accumulated in o_encbuf and successive clears
discarded them - eating contiguous multi-KB ranges of multibyte-dense output on
the unix repl console stack: 'i <cmd>' help tables displayed with missing
paragraphs, fused mid-word seam lines, or truncated bottom rows (WSL and native
linux ttys; windows unaffected). Isolation repro: 393/600 lines lost with
clear-per-write vs 0/600 without.
- tee_to_pipe: 'clear' no longer declared in initialize, so the core never
delivers it (same shape as the G-145 fix in ::punkboot::ansistrip); the
method is kept as a state-preserving no-op with a warning comment.
- flush repaired in tee_to_pipe, tee_to_log and logonly: all three referenced
an undeclared o_buffered variable (copy-paste from the o_buffered-bearing
ansiwrap/ansistrip classes) and threw on every invocation. Each now holds an
undecodable partial char in o_encbuf for the next write and emits any
decodable remainder per its class semantics.
- Verified: transform isolation harnesses clean at all chunk sizes with
clear-per-write; WSL end-to-end (linux kit visitor mode on a script(1) pty)
shows all previously-missing define/list table content present;
'make.tcl modules' mint OK.
- shellfilter-buildversion 0.2.4 -> 0.2.5; punkproject 0.49.3 -> 0.49.4 with
CHANGELOG entry; G-090 Context records the finding as audit evidence (no
characterization tests exist yet for these transforms - G-090 scope).
Claude-Session: https://claude.ai/code/session_01QgaxV27VZkmEec7oNbEVFc
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
Activation survey re-run per the freshness rule: no goals drafted since
G-160's drafting commit; top overlap remains G-035 (already Related:).
G-108/G-090 next scores are lexical-only (debug/stack vocabulary), no
new Related: lines. Survey note recorded in the detail file.
Claude-Session: https://claude.ai/code/session_01TNn3C58Cpekt3CsZNLCqvR
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
goals/AGENTS.md: Follow-ons contract - ## Follow-ons section as the last
section of archived detail files, line grammar with closed disposition
vocabulary (open | goal G-<id> | landed YYYY-MM-DD (<where>) | declined
YYYY-MM-DD (<why>)), disposition-only updates sanctioned as the one edit
to archived files (same work unit that acts on the item), archive-flip
reference sweep gains step (c) emitting the section. GOALS.md: v4 front
matter + version entry, achieved-flip and acting-on-a-follow-on
maintenance rules, authoring-workflow disposition-flip duty.
GOALS-archive.md: frozen-file carve-out wording. goals_lint.tcl: grammar
findings (malformed column-0 Follow-on line, disposition naming a goal in
neither index) - fixture-verified both fire. New goals_followons.tcl:
advisory disposition report grouping open items first + vocabulary-
without-section flags; real-archive baseline 30 flagged files (retrofit
is the next change-set).
Claude-Session: https://claude.ai/code/session_01QgaxV27VZkmEec7oNbEVFc
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
Activation survey re-run per the freshness rule: G-160/G-161 (drafted in
the interval) show no scope overlap; standing relationships unchanged
(Related: G-156). Survey note recorded in the detail file.
Claude-Session: https://claude.ai/code/session_01QgaxV27VZkmEec7oNbEVFc
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
Two user-approved proposed goals from the 2026-08-03 commandstack
characterisation arc (git 145e785c):
- G-160 commandstack hygiene pass: fix the suite-pinned defects (tokenid
stuck at 1 with duplicate-token dispatch bypass, unreachable
get_IMPLEMENTOR builtin branch, debug arg validation, stray bare puts,
Delete_stack live-rename recursion, packagepreference rename/renamer
guard key) and land the ergonomics items (did_rename record key appended,
-renamer placement errors, O(1) token dispatch, delegation helper,
Rename_stack/get_stack parking retrievability, known_renamers defaults
reconciliation). Acceptance keyed to the _GAP_ test flips; overlap survey
surfaced only G-035 (sibling surface on packagepreference, related-noted).
- G-161 tcltestrun failure parsing robust to multi-line test descriptions:
the parser currently misses multi-line opening banners, misreads the
closing banner as an opener and swallows all later events including the
summary line; goal makes it tolerant so the src/tests/AGENTS.md
single-line-description contract can stand down to style guidance.
Overlap survey: no intersecting live goals.
goals_lint: clean (84 active-index goals, 77 archived).
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
The kit launch surface dogfoods punk::args. Boot core 0.2.1 -> 0.3.0:
new built-in 'help' subcommand + '-help' / '<subcommand> -help' render
tabled usage from the moduledoc::punkexe ids plus live registrations
(per-kit resolved_def clones (script)::punkexe.launcher/.launcherhelp);
unknown first arg naming no existing file (and no lib:* reference) is
refused with usage (stderr exit 1) instead of a silent script attempt;
buildinfo enforces its no-arguments contract through punk::args (pinned
one-liner + tabled usage, exit 2 unchanged). Registration extension
::punkboot::project_subcommand_info (summary/argsid/package/parse -
documented by moduledoc::punkboot 0.2.0): project subcommands appear in
help by registration alone and may opt arguments into declared parsing.
Carve-outs: tool-style kits keep help flags routed to their processor
(tomlish parity); tclsh intercepts a help flag only as sole argument
(stock dash parity); argsid-less registrations keep -help passthrough.
G-030 degradation doctrine: lazy guarded requires (normal boots never
load punk::args), PUNKBOOT_PLAIN=1 hook, plain-list fallback, rendering
degrades independently of parsing. 8.6 trap fixed en route: punk::args
choices-grid render needs punk::lib's lpop shim - guarded require added
(verified tabled help on metakit punk86).
moduledoc::punkexe 0.4.0: (script)::punkexe::help definition; top-level
refusal rule + help discovery; per-subcommand -help notes; buildinfo
rejection shape; passthrough-vs-parsed decision recorded.
Verified on zipfs (punk902z, punk91) and metakit (punk86) kits;
launcherhelp.test 22/22 (incl fake-thin-main registration harness +
metakit leg); punkexe subtree 140/136/4skip/0fail; full suite failures
(4) are pre-existing in untouched subsystems. Goal flipped achieved +
archive record + live-tier sweep (G-038 rewrite, pointers to G-077 and
G-089); detail-file move to goals/archive follows as a pure rename.
Layout _config trio + _vfscommon core seed hand-swept (byte-identical
to masters). GOALS.md staged as the G-032-removal hunk only - the
uncommitted G-159 draft entry is left to its author.
Claude-Session: https://claude.ai/code/session_01Y1diJnhjUxKgEG6EwYAzxj
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
Acceptance fully met: per-defect dispositions recorded, module tarjar-free,
suite green (punk91 7/7, tclsh90 7/7, punk86 6/7 with the 8.6 zipfs
limitation recorded per G-034), 0.1.6 re-vendored with suite passing,
tarjar-artifact dispositions user-confirmed (all five keeps, none deleted).
Index entry moved to GOALS-archive.md; sweep updates pending-tense mentions
in G-029/G-109/G-157 and pushes actionable findings to G-034 (redirect =
zero-dep load path; 8.6 vfs::zip dll-load measured) and G-110 (8.6
copy-to-temp datapoint). Detail-file rename to goals/archive/ follows as a
pure-move commit.
Claude-Session: https://claude.ai/code/session_0156PuejSCGjgeGb7jiABrDU
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
Tar-era connection API removed from modpod (connect/disconnect/get,
system::connect_if_not/myname/myfullname - broken since the tarjar era, no
callers anywhere); is_valid_tm_version fixed (versionparts substitution
error); make_mountable_zip debug output removed (the undeclared ansistring
dependency made -offsettype file error under the module's declared deps;
stray ::last_header global gone); struct::set dependency dropped; module
greps tarjar-free. The load stub gains the unwrapped #modpod-<pkg>-<ver>
redirect: an extracted folder beside the .tm is sourced directly - loads
with neither zipfs nor vfs::zip available.
Re-vendored 0.1.6 through the established channels (modpod checkout mint ->
vendormodules -> bootsupport -> modules staging -> vfscommon). First modpod
testsuite at src/tests/modules/modpod/testsuites/modpod/roundtrip.test:
wrap/load round-trips - real-disk + zipfs module paths, both -offsettype
forms, unwrapped redirect, probe-discovered binary payload (no committed
binaries). Green: punk91 tcl9.1 kit 7/7, native tclsh90 7/7, punk86 8.6.17
6/7 (zipfs-container test skips on 8.6 - recorded per G-034).
G-111 activated at user request (activation overlap survey recorded);
per-defect dispositions, run evidence and tarjar-artifact assessment
proposals in goals/G-111-modpod-tidy-tests.md - artifact dispositions
await user confirmation. GOALS.md G-111 Scope version reference repaired
to glob form per goals-system v3 drift rule.
Claude-Session: https://claude.ai/code/session_0156PuejSCGjgeGb7jiABrDU
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
New proposed goal consuming G-101 follow-on items 1-3: punkshell 8.6
kits bake on the suite-built mk4 head via make.tcl (sdx ladder
suite-shell rung as a shared seam with G-157 step 4, bi-class head
variant, parity bakes for kit.punk86/kit.punkbi passing existing gates,
clean-path boot comparison vs tclkit-baked siblings, no new committed
binary, third-party-tclkit disposition record). Detail file carries the
2026-08-03 overlap survey (strongest: G-157; G-131/G-130/G-110/G-116/
G-137 related; libfetch/bin siblings judged not related) and the
drafting decisions approved at review.
GOALS.md staged hunk-scoped: the concurrent uncommitted G-111
activation + modpod re-vendor working state is left untouched for its
own commit.
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
Follow-on to G-004, extending the commit ban from executables to
opaque-container VFS artifacts (metakit/cookfs and similar non-zip
containers), executable-headed or not. Index entry + detail file with
overlap survey; tracked instances inventoried (bin/sdx.kit,
src/bin/sdx.kit, layout-shipped project-0.1 copy); goals_lint clean.
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
Both goals flip achieved with full acceptance verification recorded in their
detail files (G-031: componentized boot proven on punkshell kits, a generated
project and tomlish; G-025: buildinfo stamp/report verified across kit,
renamed-copy, code-interp, tclsh-hosted and unstamped contexts). Detail files
move to goals/archive/ (pure renames; flip edits committed with the move);
index entries move GOALS.md -> GOALS-archive.md records. Reference sweep per
goals/AGENTS.md Archive rules: pending-tense mentions rewritten with archive
markers and actionable outcomes pushed to G-018, G-023, G-026, G-032
(registration model + buildinfo now concrete render sources), G-038 (piped
exitinfo quirk re-measured and recorded as its territory), G-089
(boot_state IS the packagemode hint surface), G-131 (mains collapsed - land
detection in the core), G-137 (stamp exists - reconcile RT_VERSION against
it). goals_lint clean (81 active, 75 archived).
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
