From 5bf9c83103e2149fb038d5abea6b55b061a78e1f Mon Sep 17 00:00:00 2001 From: Julian Noble Date: Thu, 6 Aug 2026 17:06:11 +1000 Subject: [PATCH] G-170 follow-on landed: argsid formhint authoring note in punkboot moduledoc (0.3.2) The registration definition's 'argsid' key text now notes that a multi-form project definition may carry its own '@cmd -formhint' template of the shape ' help %formname%' - the launcher narrows 'help ' (exact form name or decimal ordinal) to that form's usage, so the hinted line names real navigation. Authored with NO trailing ellipsis per the display-hint honesty rule: words after the form word are not a continuation of the narrowed render - on a parse=1 registration they dry-run through argsid instead. Doc-only patch bump 0.3.1 -> 0.3.2; follow-on disposition flipped to landed in goals/archive/G-170-launcher-help-depth.md. Verified: live render probe via bin/punk91 src script (definition parses, note renders in the argsid column), goals_lint clean, goals_followons reports the item landed, make.tcl modules mint green (punkboot-0.3.2.tm). No project-version bump - the doc-only source edit ships at the user-owned promotion+bake, where the project-version gate covers the pending bump. Claude-Session: https://claude.ai/code/session_01SCqtCXT1q45sjjMFfwARRj Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com --- goals/archive/G-170-launcher-help-depth.md | 2 +- .../punk/args/moduledoc/punkboot-999999.0a1.0.tm | 11 +++++++++++ .../punk/args/moduledoc/punkboot-buildversion.txt | 3 ++- 3 files changed, 14 insertions(+), 2 deletions(-) diff --git a/goals/archive/G-170-launcher-help-depth.md b/goals/archive/G-170-launcher-help-depth.md index 66e25795..1f8ded8c 100644 --- a/goals/archive/G-170-launcher-help-depth.md +++ b/goals/archive/G-170-launcher-help-depth.md @@ -168,4 +168,4 @@ Verification evidence: ## Follow-ons Follow-on: coherent-set promotion - the same vfscommonupdate/bake event as G-169's open promotion line, now additionally carrying punkboot core 0.7.0 + punkexe moduledoc 0.9.0 + app-punkscript 1.3 (with punk::args 0.18.0 + punk::ansi 0.2.0 for the landing report); mixed intermediate states degrade gracefully by construction (fence witness, guarded parse_report) => landed 2026-08-06 (promotion + bake: bootsupport punk::args 0.18.0 + punk::ansi 0.2.0; _vfscommon.vfs punkboot core 0.7.0 + punkexe moduledoc 0.9.0 + punkboot moduledoc 0.3.1 + app-punkscript 1.3; 11 kits rebaked and deployed - the deployed kit now serves narrowing, formhint labels and the parse_report dry-run, and the tclsh fence witness is satisfied so its dry-run is live instead of the historic ignored-tail render) -Follow-on: punkboot moduledoc registration guidance - note at the 'argsid' key that a multi-form project definition may carry its own '@cmd -formhint " help %formname%"' template now that the launcher narrows on form words (project parse=1 dry-run and narrowing already work; only the authoring hint is missing) => open +Follow-on: punkboot moduledoc registration guidance - note at the 'argsid' key that a multi-form project definition may carry its own '@cmd -formhint " help %formname%"' template now that the launcher narrows on form words (project parse=1 dry-run and narrowing already work; only the authoring hint is missing) => landed 2026-08-06 (punkboot moduledoc 0.3.2: authoring note added at the registration definition's 'argsid' key - formhint template shape, exact-formname/ordinal narrowing, NO trailing ellipsis per display-hint honesty) diff --git a/src/modules/punk/args/moduledoc/punkboot-999999.0a1.0.tm b/src/modules/punk/args/moduledoc/punkboot-999999.0a1.0.tm index 1bfa4878..50b7f323 100644 --- a/src/modules/punk/args/moduledoc/punkboot-999999.0a1.0.tm +++ b/src/modules/punk/args/moduledoc/punkboot-999999.0a1.0.tm @@ -122,6 +122,17 @@ tcl::namespace::eval punk::args::moduledoc::punkboot { arguments - help flags included, 2026-08-05 single-mechanism revision - so an app may do its own -help handling regardless.) + A multi-form definition may carry its own + '@cmd -formhint' template of the shape + ' help %formname%' (G-170): the + launcher narrows 'help ' (exact + form name, or decimal ordinal) to that form's + usage, so the hinted line names real navigation. + Author it with NO trailing ellipsis (display-hint + honesty): words after the form word are not a + continuation of the narrowed render - on a + parse=1 registration they dry-run through argsid + instead. package package to require (guarded) before resolving argsid - typically a moduledoc-style package carrying the definition, or an app-owned docs diff --git a/src/modules/punk/args/moduledoc/punkboot-buildversion.txt b/src/modules/punk/args/moduledoc/punkboot-buildversion.txt index 0da320ce..9b4a09d8 100644 --- a/src/modules/punk/args/moduledoc/punkboot-buildversion.txt +++ b/src/modules/punk/args/moduledoc/punkboot-buildversion.txt @@ -1,6 +1,7 @@ -0.3.1 +0.3.2 #First line must be a semantic version number #all other lines are ignored. +#0.3.2 - documentation-only (G-170 follow-on): the registration definition's 'argsid' key text now notes that a multi-form definition may carry its own '@cmd -formhint' template of the shape ' help %formname%' - the launcher narrows 'help ' (exact form name or decimal ordinal) so the hinted line names real navigation; authored with NO trailing ellipsis per the display-hint honesty rule (words after the form word are not a continuation of the narrowed render - on a parse=1 registration they dry-run through argsid) #0.3.1 - documentation-only (G-169): the registration definition's 'package' key text now documents the app-owned docs-package pattern (an execution-gated source of the app's own file, so a subcommand's definition lives beside its parsing code and the help path never runs the app - the app-punkscript-docs precedent for the built-in 'script' subcommand, with the gate shape in src/lib/app-punkscript/pkgIndex.tcl). This registration definition is the recorded durable-doc location for the *_main.tcl declaration keys (summary/argsid/package/parse incl the parse=1 gate), alongside the punkboot_core.tcl header contract and the project_main.tcl worked examples. #0.3.0 - single-mechanism revision (2026-08-05, user direction): help-flag interception withdrawn from the launcher - registration argsid text now names 'help ' as the only launcher-rendered route (apps own their -help handling); unknownfirst text covers the G-077 '-e' one-liner and states help flags are never intercepted #0.2.0 - G-032 registration surface extension documented: project_subcommand_info (summary/argsid/package/parse) in the registration definition + thin-main obligations; built-in list gains help; launcher help/flag semantics (unknownfirst=script gate, argsid-gated -help interception) recorded