Browse Source
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
master
5 changed files with 103 additions and 1 deletions
@ -0,0 +1,36 @@
|
||||
# G-168 Selection-sound launch definitions: script/tclsh forms match dispatch reality |
||||
|
||||
Status: proposed |
||||
Scope: src/modules/punk/args/moduledoc/punkexe-999999.0a1.0.tm ((script)::punkexe::script + ::tclsh form discrimination); src/lib/app-punkscript/punkscript.tcl (behaviour oracle, error-surface decision); src/vfs/_config/punkboot_core.tcl (only if the dispatch-parse decision adopts gating, + synced copies via established channels); src/tests/modules/punk/args/testsuites/args/ (new model-parity suite); src/tests/shell/testsuites/punkexe/launcherhelp.test (as touched) |
||||
Goal: The two multi-form launch-subcommand definitions are parse-discriminable with existing punk::args vocabulary - form auto-selection agrees with actual dispatch/app behaviour: the file form excludes exactly '-e' (-regexprefail {^-e$}, message naming ./-e), the oneliner form declares the '-e' word as a real element, and tclsh's scriptfile-vs-stdin split (leading-dash words stay argv; incomplete -encoding falls through, stock-style) is expressed through candidacy fall-through - so parse_status verdicts, noformmatch diagnoses and downstream consumers (help depth, completion) see the truth instead of a display-only model. |
||||
Acceptance: against the script definition, parse/parse_status select oneliner for {-e <code> ...}, select file for {<word> ...} where <word> ne -e, and {-e} alone reports noformmatch with oneliner viable-incomplete (the app's "-e requires a script argument" reality); against tclsh, {file args} selects scriptfile, a leading-dash word selects stdin, and an incomplete -encoding tail falls through to stdin (stock parity); formcheck reports no unsanctioned findings; a real-vs-model probe matrix (G-055 method) against actual dispatch/app-punkscript behaviour is recorded in this file; whether DISPATCH adopts parse-gating for script/tclsh (tabled pointed errors replacing app-punkscript's plain ones) is decided and recorded with rationale and, if adopted, a measured script-launch latency delta; the new behaviour is pinned in the args testsuite and launcherhelp.test passes unchanged (or with deliberately updated pins named here). |
||||
|
||||
## Context |
||||
|
||||
2026-08-05 discussion (formhint arc): 'punk9-dev -e' / 'script -e' error - word-1 |
||||
'-e' is RESERVED by behaviour (app-punkscript punkscript.tcl:78-88; a file so |
||||
named needs ./-e), but the file form declares scriptfile as any string - the |
||||
definition is display-honest, parse-dishonest, and the forms cleanly double-match. |
||||
The blocker assumed earlier (G-072 negation) is not needed: -regexprefail is |
||||
honoured during form matching (verified in the G-143 make.tcl arc, achieved - |
||||
goals/archive/G-143-maketcl-multiform-help.md; the G-150 selection-sound hash |
||||
declaration is the dash-led-form-word precedent). |
||||
|
||||
## Notes |
||||
|
||||
- Enacts the punkexe portion of the G-150 follow-on "sweep other flat multi-form |
||||
definitions for selection-soundness" (goals/archive/G-150-cmdhelp-form-narrowing.md); |
||||
that follow-on stays open - the sweep is broader than these two definitions. |
||||
- The G-144 follow-on (punkexe moduledoc @form -synopsis override set drops once |
||||
auto-synopsis serves - goals/archive/G-144-punkargs-synopsis-name-fallback.md, |
||||
disposition flipped to this goal) is decided in this work: keep the <punkexe> |
||||
placeholder overrides or adopt @cmd -name auto lines - recorded either way. |
||||
- Related: G-089 (proposed) - script's lib:name resolution text is consumed scope. |
||||
- Related: G-055 (proposed) - the real-vs-model probe method borrowed here. |
||||
- Related: G-072 (proposed) - deliberate non-dependency: negation NOT required. |
||||
- Related: G-170 (proposed) - consumer: its dry-run arm requires this goal's |
||||
parse-trueness. |
||||
- Overlap survey 2026-08-05: goals_xref paths over the Scope - G-089 (named |
||||
above) is the only substantive live intersection on punkboot_core.tcl; |
||||
moduledoc-sibling matches (G-055 G-068 G-072 G-083 G-084 G-166 G-167) are |
||||
parser/spec mechanisms or other moduledocs, no availability interaction. |
||||
@ -0,0 +1,28 @@
|
||||
# G-169 App-owned launch-subcommand documentation consumed by the launcher |
||||
|
||||
Status: proposed |
||||
Scope: src/lib/app-punkscript/punkscript.tcl (carries its subcommand's punk::args definition via inert registration); src/modules/punk/args/moduledoc/punkexe-999999.0a1.0.tm (single-definer handover); src/vfs/_config/punkboot_core.tcl (built-in help resolution via app-owned ids, *_main.tcl declaration surface documented, + synced copies via established channels); src/tests/shell/testsuites/punkexe/launcherhelp.test |
||||
Goal: A subcommand's punk::args definition can live in its handling app and the launcher consumes it - proven on app-punkscript owning (script)::punkexe::script (inert PUNKARGS registration, no load-time side effects, lazily resolved at help/error time) with the moduledoc entry handed over (one definer per id); the ownership rule is recorded (docs live with the owning code - app-owned for app-handled subcommands, moduledoc for core-owned surfaces like tclsh); and the existing *_main.tcl project-subcommand declaration surface (summary/package/argsid/parse) is documented as the official authoring mechanism it already is. |
||||
Acceptance: app-punkscript carries the script definition and 'help script' renders it on a baked kit via lazy resolution (guarded package require + docpackages/argsid - no eager load at boot; help-path load cost measured and recorded); the punkexe moduledoc no longer defines the id (no duplicate-definition warnings; single definer verified); degraded/plain help path intact; the *_main.tcl declaration keys are documented where kit authors look (location decided in the work: core header contract + a durable doc) including the parse=1 gate; launcherhelp.test passes with a new app-owned-resolution pin. |
||||
|
||||
## Context |
||||
|
||||
2026-08-05 discussion: the actual '-e' parsing lives in app-punkscript while its |
||||
documentation lives in the punkexe moduledoc - co-location kills that drift |
||||
class. Nothing structural prevents launcher consumption of app-owned docs: the |
||||
argsid+package indirection and parse=1 gate already exist for project |
||||
subcommands (punkboot_core.tcl:1779-1791, 2168-2192), and punk::args 0.12.7's |
||||
docpackages association loads a documenting package lazily on first usage query. |
||||
The moduledoc pattern remains right where implementation is external or |
||||
core-owned (tclcore precedent: separation + parity pins). |
||||
|
||||
## Notes |
||||
|
||||
- Coordination with G-168: either order works; whichever lands second edits the |
||||
definition at its then-current home (never two definers). |
||||
- Related: G-075 (proposed) - sibling documentation-reachability surface. |
||||
- Related: G-042/G-043 (proposed) - adjacent declaration-composition patterns; |
||||
deliberate non-overlap (launch surface, not repl subshells). |
||||
- Overlap survey 2026-08-05: app-punkscript intersects no live goals; the |
||||
punkboot_core.tcl matches are the G-168 survey's set (G-089 nearest, others |
||||
incidental). |
||||
@ -0,0 +1,26 @@
|
||||
# G-170 Launcher help depth: form narrowing, parse-true dry-run, actionable form hints |
||||
|
||||
Status: proposed |
||||
Scope: src/vfs/_config/punkboot_core.tcl (help arm, + synced copies via established channels); punkexe launch definitions wherever homed after G-168/G-169 (formhint un-suppression); src/tests/shell/testsuites/punkexe/launcherhelp.test |
||||
Goal: Launcher help gains per-form depth without breaking the prepend-help idiom: 'help <sub> <formname|index>' narrows any multi-form definition to that form's usage (the G-150 cmdhelp/usage -form precedent); for parse-true subcommands (G-168 built-ins; project registrations with parse=1) the help tail MAY dry-run make.tcl-style - accepted lines render the matched form plus the received-args report, rejected lines emit dispatch's own diagnosis - while passthrough subcommands keep ignored tails exactly as today; and the 0.6.1 interim -formhint suppression is replaced with actionable ' <punkexe> help <sub> %formname%' templates, resolving the circularity objection (the hint names real navigation). |
||||
Acceptance: 'help script oneliner' (and an index form) renders only that form's usage; a non-form trailing word on a passthrough subcommand keeps today's ignored behaviour (prepend-help pinned unchanged); for a parse-true subcommand the dry-run's accept/reject agrees with dispatch on the same words (parity pinned); the form-word-vs-scriptfile collision rule (a script literally named 'oneliner') is decided and documented; the multi-form definitions' -formhint suppression flips to real templates and the hint labels render them; every increment has a working degraded/plain twin; all pinned in launcherhelp.test. |
||||
|
||||
## Context |
||||
|
||||
The G-149 make.tcl adoption (2026-08-05 - goals/archive/G-149-punkargs-formhint-labels.md) |
||||
showed the hint pattern; the launcher suppressed instead (punkexe moduledoc |
||||
0.6.1) because subject-only help offered no per-form destination. This goal |
||||
builds the destination, then points at it. |
||||
|
||||
## Notes |
||||
|
||||
- Depends on G-168 (proposed) for the dry-run arm (narrowing arm is standalone). |
||||
- Related: G-169 (proposed) - the defs' home determines where templates land. |
||||
- Related: G-044 (proposed) - completion later consumes the same candidacy data. |
||||
- Archived precedents: G-143 (achieved - goals/archive/G-143-maketcl-multiform-help.md, |
||||
make.tcl dry-run), G-150 (achieved - goals/archive/G-150-cmdhelp-form-narrowing.md, |
||||
usage -form narrowing), G-032 (achieved - goals/archive/G-032-launcher-punkargs.md, |
||||
launcher help mechanism), G-149 (achieved - goals/archive/G-149-punkargs-formhint-labels.md, |
||||
formhint mechanism + suppression). |
||||
- Overlap survey 2026-08-05: shared with the G-168/G-169 survey; no additional |
||||
live intersections beyond those named. |
||||
Loading…
Reference in new issue