From 2cc0568dc744cba84925910ec16dbf66fedc8255 Mon Sep 17 00:00:00 2001 From: Julian Noble Date: Tue, 4 Aug 2026 16:01:54 +1000 Subject: [PATCH] G-150 achieved 2026-08-04: flip + archive (punk::ns cmdhelp form narrowing + selection-sound auto_exec::hash declaration) 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 ' 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 --- GOALS-archive.md | 4 ++++ GOALS.md | 4 ---- goals/{ => archive}/G-150-cmdhelp-form-narrowing.md | 13 ++++++++++++- 3 files changed, 16 insertions(+), 5 deletions(-) rename goals/{ => archive}/G-150-cmdhelp-form-narrowing.md (52%) diff --git a/GOALS-archive.md b/GOALS-archive.md index a8e29f75..6e738966 100644 --- a/GOALS-archive.md +++ b/GOALS-archive.md @@ -20,6 +20,10 @@ Do not edit archived records here except to fix a broken path. Archived detail f ## Archived goals +### G-150 [achieved 2026-08-04] punk::ns cmdhelp form narrowing + selection-sound auto_exec::hash declaration → detail: goals/archive/G-150-cmdhelp-form-narrowing.md +Scope: src/modules/punk/ns-999999.0a1.0.tm (cmdhelp); src/modules/punk/auto_exec-999999.0a1.0.tm (hash definition); src/tests/modules/punk/ns/testsuites/ (cmdhelp + auto_exec pins) +Acceptance: 'i ::punk::auto_exec::hash -r' renders only the rehash form's usage and 'i ::punk::auto_exec::hash -d ' only the delete form, driven by the definition (no hash-handler involvement); hash's plain name value carries a flag-excluding constraint (-regexprefail {^-} or equivalent) such that bare punk::args::parse withid selects flag-led forms uniquely, with hash's runtime behaviour otherwise unchanged (a name literally starting with '-' now requires explicit -form selection - the accepted cost); ensembles, single-form commands and no-word invocations render as today (existing cmdhelp behaviour pinned unchanged); the behaviours are pinned in the module testsuites. + ### G-077 [achieved 2026-08-04] punk executable -e one-liner support: make the tclsh-agent instinct work → detail: goals/archive/G-077-punkexe-dash-e-oneliner.md Scope: src/vfs/_config/punk_main.tcl (top-level arg dispatch); src/lib/app-punkscript/punkscript.tcl (script subcommand arg forms); src/tests/shell/testsuites/punkexe/scriptexec.test Acceptance: `punksys -e {puts hi}` and `punk902z script -e {puts hi}` print hi and exit 0 with and without piped stdin present (the one-liner may itself read stdin); a -e with no following script argument is a usage error, never an interactive fall-through; error in the one-liner prints errorInfo to stderr and exits 1 (matching the script subcommand's file form); scriptexec.test covers the above against the built executable. diff --git a/GOALS.md b/GOALS.md index b0b3e96a..1651bcfe 100644 --- a/GOALS.md +++ b/GOALS.md @@ -380,10 +380,6 @@ Detail: goals/G-148-vendor-upstream-discovery.md Scope: src/modules/punk/args-999999.0a1.0.tm (usage/arg_error multi-form Synopsis hint column); src/tests/modules/punk/args/testsuites/args/ Detail: goals/G-149-punkargs-formhint-labels.md -### G-150 [proposed] punk::ns cmdhelp form narrowing + selection-sound auto_exec::hash declaration -Scope: src/modules/punk/ns-999999.0a1.0.tm (cmdhelp); src/modules/punk/auto_exec-999999.0a1.0.tm (hash definition); src/tests/modules/punk/ns/testsuites/ (cmdhelp + auto_exec pins) -Detail: goals/G-150-cmdhelp-form-narrowing.md - ### G-151 [proposed] punk::args annotated success render (received-args landing report) Scope: src/modules/punk/args-999999.0a1.0.tm (parse-result presentation); src/tests/modules/punk/args/testsuites/args/ Detail: goals/G-151-punkargs-annotated-success-render.md diff --git a/goals/G-150-cmdhelp-form-narrowing.md b/goals/archive/G-150-cmdhelp-form-narrowing.md similarity index 52% rename from goals/G-150-cmdhelp-form-narrowing.md rename to goals/archive/G-150-cmdhelp-form-narrowing.md index 6de775fe..00752094 100644 --- a/goals/G-150-cmdhelp-form-narrowing.md +++ b/goals/archive/G-150-cmdhelp-form-narrowing.md @@ -1,6 +1,6 @@ # G-150 punk::ns cmdhelp form narrowing + selection-sound auto_exec::hash declaration -Status: proposed +Status: achieved 2026-08-04 Scope: src/modules/punk/ns-999999.0a1.0.tm (cmdhelp); src/modules/punk/auto_exec-999999.0a1.0.tm (hash definition); src/tests/modules/punk/ns/testsuites/ (cmdhelp + auto_exec pins) Goal: 'i ?word ...?' (punk::ns::cmdhelp) narrows a flat multi-form command to the form its trailing words select - punk::args form auto-selection, with the whole-command render retained when no form is selectable (no words, option-first lines, ambiguity) - and punk::auto_exec::hash's definition is selection-sound so it exemplifies the mechanism: a flag-led line selects its flag form uniquely instead of today's 'Ambiguous arguments' outcome on a bare parse-withid. Acceptance: 'i ::punk::auto_exec::hash -r' renders only the rehash form's usage and 'i ::punk::auto_exec::hash -d ' only the delete form, driven by the definition (no hash-handler involvement); hash's plain name value carries a flag-excluding constraint (-regexprefail {^-} or equivalent) such that bare punk::args::parse withid selects flag-led forms uniquely, with hash's runtime behaviour otherwise unchanged (a name literally starting with '-' now requires explicit -form selection - the accepted cost); ensembles, single-form commands and no-word invocations render as today (existing cmdhelp behaviour pinned unchanged); the behaviours are pinned in the module testsuites. @@ -16,3 +16,14 @@ From the G-143 finalisation sessions (2026-08-01/02 - archived detail file's Pro - Related: G-143 (achieved 2026-08-01 - goals/archive/G-143-maketcl-multiform-help.md) - the make.tcl help dry-run contract this mirrors at the repl. - G-152 (achieved 2026-08-02 - goals/archive/G-152-punkargs-form-viability-verdict.md) shipped the suffix-viability verdict this goal's failed/incomplete-line narrowing consumes: formstatus statuses and noformmatch errorcode classes are now sound per-form verdicts, and rendered noformmatch form lines carry '(viable - needs more arguments)' / '(not viable)' markers. Note bootsupport punk::args was still 0.13.0 at G-152 archive time - refresh bootsupport when this goal wants the verdict at the make.tcl surface. - Overlap survey 2026-08-02: goals_xref paths src/modules/punk/ns-999999.0a1.0.tm src/modules/punk/auto_exec-999999.0a1.0.tm - ns family G-044 G-050 G-052 G-075 G-085 (G-052 autodef docs and G-085 cmdtrace are unrelated mechanisms; G-075 package-id docs tangential); no auto_exec-scoped goals surfaced. +- Activation freshness re-run 2026-08-04 (goals_xref score G-150): no new related goals since drafting - the strongest unlinked pairs (G-055/G-141/G-013/G-109/G-110 term noise on args/word/definition; G-052/G-050/G-044/G-075/G-085 one-directionals already surveyed above) are unrelated mechanisms. No new Related lines required. + +## Progress + +- 2026-08-04 IMPLEMENTED (auto_exec 0.1.1, ns 0.9.2, punkshell 0.51.0): the goal reduced to its declaration half - cmdhelp's G-041 advisory-parse candidacy already narrowed on a unique form selection (verified live pre-change: 'i hash foo' presented show_or_set); the missing piece was hash's selection-soundness. hash's show_or_set name value gained -regexprefail {^-} (mirroring the handler's long-standing first-word rejection of dash-led names), so bare punk::args::parse/parse_status of {-r}/{-d }/{-t } selects rehash/delete/test uniquely (previously multipleformmatches with show_or_set). cmdhelp code unchanged; its subcommand argdoc now states the narrowing contract explicitly. Test-environment gotcha recorded: tcltest setup/body scripts run at namespace level in ::testspace where 'global' is a no-op - the runtime-unchanged pin qualifies ::auto_execs explicitly. +- 2026-08-04 VERIFIED (native tclsh 8.7a6 via runtests.tcl): acceptance pinned in src/tests/modules/punk/ns/testsuites/ns/cmdhelp.test (8 new tests: cmdhelp_multiform_flagled_narrowing_rehash / _delete, auto_exec_hash_bare_parse_selects_flag_forms, auto_exec_hash_dashled_name_no_longer_plain, cmdhelp_multiform_nowords_whole_render_retained, cmdhelp_multiform_unknown_flag_noformmatch_whole_render, cmdhelp_multiform_ambiguity_whole_render, auto_exec_hash_runtime_behaviour_unchanged) - cmdhelp.test 40/40; ns subtree green apart from the 2 pre-existing nsprimitives environment failures on this box (verified pristine-failing identically); full source-tree -jobs 16 run at parity with the recorded pre-existing environment failures (21 - exec.test 5, argparsingtest 5, commandstack 1, modpod roundtrip 1, lib compat lpop 1, nsprimitives 2, repl consolebackends/nscurrent SIGILL 4, zipreader 2, offsetstyle 1; commandstack/modpod/offsetstyle separately verified failing identically on the pristine tree in multiproc mode). 'i ::punk::auto_exec::hash -r' / '-d foo' additionally verified live in the interactive table surface (whole header + all-form synopsis with only the selected form's argument table, no ambiguity message) beyond the pinned string/text/dict surfaces. make.tcl modules mint clean (auto_exec-0.1.1.tm, ns-0.9.2.tm); bootsupport/vfscommon promotion left to the next promotion cycle (per the 0.50.1 precedent). + +## Follow-ons + +Follow-on: hash handler's multi-name -t missing-name branch prints "$hash: nm: not found" - undefined variable $hash and literal 'nm:' (auto_exec-*.tm) - pre-existing defect surfaced by this goal's runtime pins, deliberately out of scope => landed 2026-08-04 (user fix in src/modules/punk/auto_exec-999999.0a1.0.tm, folded into auto_exec 0.1.1; regression pin auto_exec_hash_test_multi_missing_name_message in cmdhelp.test) +Follow-on: sweep other flat multi-form punk::args definitions for selection-soundness (an unconstrained plain value swallows flag-like words, making every flag-led line ambiguous) - hash was this goal's exemplar; other definitions opt in per-definition => open