From b0f206f53b9e6330b9f701d81bfc2bb552bdbeb5 Mon Sep 17 00:00:00 2001 From: Julian Noble Date: Wed, 5 Aug 2026 16:32:59 +1000 Subject: [PATCH] G-168/G-169/G-170 drafted: launcher definition/documentation/help-depth family (user-approved) 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 ' 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 ' help %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 --- GOALS.md | 12 +++++++ ...-168-selection-sound-launch-definitions.md | 36 +++++++++++++++++++ goals/G-169-app-owned-launch-docs.md | 28 +++++++++++++++ goals/G-170-launcher-help-depth.md | 26 ++++++++++++++ .../G-144-punkargs-synopsis-name-fallback.md | 2 +- 5 files changed, 103 insertions(+), 1 deletion(-) create mode 100644 goals/G-168-selection-sound-launch-definitions.md create mode 100644 goals/G-169-app-owned-launch-docs.md create mode 100644 goals/G-170-launcher-help-depth.md diff --git a/GOALS.md b/GOALS.md index ec5c4e8c..056d6ae2 100644 --- a/GOALS.md +++ b/GOALS.md @@ -405,3 +405,15 @@ Detail: goals/G-166-cmdinfo-unavailable-surfacing.md ### G-167 [proposed] punk::args version-delta availability: unavailable @forms for shape deltas, unavailable option names for flag deltas Scope: src/modules/punk/args-999999.0a1.0.tm (form selection/candidacy availability filter + tailored raises, option-scan unavailable-name recognition, synopsis/table renderers - annotated form lines, unavailable option rows, automated other-shapes note, formstatus 'available' field, -form display-vs-parse split); src/modules/punk/ns-999999.0a1.0.tm (cmdhelp -return text form-section heading annotation; form narrowing inherits the availability filter); src/modules/punk/args/moduledoc/tclcore-999999.0a1.0.tm (adoption on curated real 8.6-vs-9 deltas); src/tests/modules/punk/args/testsuites/args/ (new suite + formviability/tclcoreparity extensions) Detail: goals/G-167-punkargs-version-delta-availability.md + +### G-168 [proposed] Selection-sound launch definitions: script/tclsh forms match dispatch reality +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) +Detail: goals/G-168-selection-sound-launch-definitions.md + +### G-169 [proposed] App-owned launch-subcommand documentation consumed by the launcher +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 +Detail: goals/G-169-app-owned-launch-docs.md + +### G-170 [proposed] Launcher help depth: form narrowing, parse-true dry-run, actionable form hints +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 +Detail: goals/G-170-launcher-help-depth.md diff --git a/goals/G-168-selection-sound-launch-definitions.md b/goals/G-168-selection-sound-launch-definitions.md new file mode 100644 index 00000000..9e7e4636 --- /dev/null +++ b/goals/G-168-selection-sound-launch-definitions.md @@ -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 ...}, select file for { ...} where 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 + 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. diff --git a/goals/G-169-app-owned-launch-docs.md b/goals/G-169-app-owned-launch-docs.md new file mode 100644 index 00000000..1fc796fc --- /dev/null +++ b/goals/G-169-app-owned-launch-docs.md @@ -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). diff --git a/goals/G-170-launcher-help-depth.md b/goals/G-170-launcher-help-depth.md new file mode 100644 index 00000000..809bfe7c --- /dev/null +++ b/goals/G-170-launcher-help-depth.md @@ -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 ' 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 ' help %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. diff --git a/goals/archive/G-144-punkargs-synopsis-name-fallback.md b/goals/archive/G-144-punkargs-synopsis-name-fallback.md index 6afd49c1..01c552a1 100644 --- a/goals/archive/G-144-punkargs-synopsis-name-fallback.md +++ b/goals/archive/G-144-punkargs-synopsis-name-fallback.md @@ -45,4 +45,4 @@ The goal text named "(shared)/(package)-style doc ids" alongside (script) as ben ## Follow-ons -Follow-on: make.tcl drops its per-definition @form -synopsis overrides and the punkexe moduledoc's override set once the @cmd -name fallback serves them => open +Follow-on: make.tcl drops its per-definition @form -synopsis overrides and the punkexe moduledoc's override set once the @cmd -name fallback serves them => goal G-168