goals: weave 2026-07-14 session residue - G-082 proposed (punk::args error selection), sibling notes in G-025/G-028/G-073/G-075

New proposed goal G-082: single-form parse error selection should prefer an
optional argument's specific choice/type rejection over the generic
"more values than can be assigned" overflow (regression vs punk::args 0.5.0
found while dogfooding in G-030; the -optional 0 workaround sites in make.tcl
and the AGENTS authoring-ergonomics bullet are flagged for revisiting when it
ships).

Sibling notes parked in existing proposed goals:
- G-028: make.tcl's name-only process-sweep misidentification (unrelated
  same-named executables) - full-path matching rides the same
  process-identification infrastructure as the locker report.
- G-025: punk-exe-hosted make.tcl runs the kit's pre-loaded module copies, not
  bootsupport snapshots - a self-report surface for running-interp module
  provenance would make the mixing observable.
- G-073: reciprocal relation to G-082 (both want the "surface the specific
  rejection" seam in validation error reporting).
- G-075: synopsis renders the definition id rather than @cmd -name - consider
  a fallback for non-command ids when reworking id rendering.

goals_lint: unchanged (only the pre-existing G-078/G-081 index-mirror findings).

Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com

GOALS.md

@@ -309,3 +309,7 @@ Detail: goals/G-080-ansi2html-cellgrid-mode.md
 ### G-081 [proposed] punk::args documentation build pipeline (dev doc.* integration)
 Scope: src/modules/punk/mix/commandset/doc-999999.0a1.0.tm (doc.* generation subcommands), src/scriptapps/tools/punkargs_to_doctools.tcl + punkargs_punknative.tcl (productize), src/scriptapps/tools/fontprep/ (shared doc-set asset), src/doc tree conventions, src/tests coverage
 Detail: goals/G-081-argdoc-build-pipeline.md
+
+### G-082 [proposed] punk::args single-form parse error selection: specific validation failures preferred over generic overflow
+Scope: src/modules/punk/args-999999.0a1.0.tm (get_dict/parse error selection, validation-failure capture around the choice/type screens), src/tests/modules/punk/args/testsuites/args/ (characterization + regression suite)
+Detail: goals/G-082-punkargs-error-selection.md

goals/G-025-exe-selfreport.md

@@ -81,4 +81,13 @@ Edge cases driving the acceptance clauses:
 - Related: G-023 (version-named binaries this complements), G-024 (build
   mapping that will drive stamping inputs), G-015 (piped invocation of the
   subcommand), G-014 (punkproject.toml reading may share tomlish plumbing).
+- Adjacent need surfaced 2026-07-14 (G-030 follow-up, recorded in
+  src/AGENTS.md "pre-loaded interp" note): when make.tcl runs under a built
+  punk executable, the module copies actually executing are the kit's
+  pre-loaded ones, not the bootsupport snapshots make.tcl's paths would
+  prefer - silent provenance mixing whenever versions diverge. A self-report
+  surface that can also state, for a RUNNING interp, which copy of each key
+  punk module is loaded and where it came from (kit vfs / bootsupport /
+  dev paths) would make that mixing observable instead of silent.
+  (G-030 achieved 2026-07-14 - goals/archive/G-030-maketcl-punkargs.md)
 - Archived-goal references in this file: G-007 achieved 2026-07-05 (goals/archive/G-007-console-location-transparency.md);G-015 achieved 2026-07-07 (goals/archive/G-015-script-subcommand-piped-stdin.md).

goals/G-028-file-locker-identification.md

@@ -66,3 +66,12 @@ the kind of file this fails on.
 - Unix analogues (lsof/fuser) could slot behind the same helper interface
   later; out of scope for acceptance (Windows is where the pain is and where
   the API answer is non-obvious).
+- Sibling candidate parked here 2026-07-14 (G-030 follow-up): make.tcl's
+  pre-deploy process sweep matches processes by executable NAME only (tasklist
+  gives no path), so an unrelated same-named executable elsewhere on the system
+  can be killed - the code's own TODO. The sweep now excludes the build's own
+  pid and the self-build target kit is skipped entirely, but other-instance
+  misidentification remains; full-path process matching (powershell get-process,
+  or the same Restart-Manager-adjacent infrastructure this goal introduces)
+  is the fix, and a locker-report helper that returns paths would serve both.
+  (G-030 achieved 2026-07-14 - goals/archive/G-030-maketcl-punkargs.md)

goals/G-073-punkargs-unavailable-choices.md

@@ -62,3 +62,8 @@ riding the existing rendering pipeline.
   once proven here).
 - The reject-message wording should steer the user: name the note/annotation and
   the version boundary, not just "invalid".
+- Related: G-082 (proposed 2026-07-14) - single-form error selection currently
+  discards an optional argument's specific choice/type rejection in favour of a
+  generic overflow error; this goal's tailored unavailable-choice message wants
+  the same "surface the specific rejection" seam. Whichever lands first should
+  leave the other a clean hook.

goals/G-075-punkargs-package-ids.md

@@ -65,3 +65,11 @@ place, once reachable.
 - 45 declaring modules found 2026-07-13 via grep for '"(package)' under src/modules
   (plus decktemplates vendor copies); count will drift - the acceptance names the
   four moduledocs + one template-created module as the proving set, not all 45.
+- Adjacent id-rendering nicety parked here 2026-07-14 (G-030 lesson): the
+  auto-generated synopsis renders the definition id, not @cmd -name - so
+  script-level/constructed ids like (script)::punkboot::modules display raw
+  unless an explicit @form -synopsis is supplied (make.tcl does this; the
+  authoring-ergonomics bullet in src/modules/AGENTS.md documents it). While
+  reworking how non-command id prefixes render, consider a synopsis fallback
+  to @cmd -name when the id is not a real command path.
+  (G-030 achieved 2026-07-14 - goals/archive/G-030-maketcl-punkargs.md)

goals/G-082-punkargs-error-selection.md

@@ -0,0 +1,39 @@
+# G-082 punk::args single-form parse error selection: specific validation failures preferred over generic overflow
+
+Status: proposed
+Scope: src/modules/punk/args-999999.0a1.0.tm (get_dict/parse error selection, validation-failure capture around the choice/type screens), src/tests/modules/punk/args/testsuites/args/ (characterization + regression suite)
+Goal: when a single-form parse fails because a word was rejected by an optional argument's validation (restricted choices, type) and consequently overflowed the argument list, the reported error names the specific rejection (the choiceviolation with the offending word and choice list, or the type failure) instead of the generic "Received more values than can be assigned" overflow - restoring the pointedness punk::args 0.5.0-era parsing had for optional choice-restricted leaders/values, and removing the need for the -optional 0 authoring workaround adopted by make.tcl's dispatch definitions.
+Acceptance: a definition with an optional choice-restricted leader or value that receives a non-matching word reports a choiceviolation-class error naming the word and the allowed choices (message and -errorcode), not toomanyarguments - pinned for the make.tcl-style dispatch shape (optional subcommand leader with choices) and a values-position equivalent; a word rejected by a typed optional argument (e.g int) that then overflows reports the type failure similarly; genuinely-surplus cases (all optional args satisfied, extra word remains) still report toomanyarguments; multiform error selection (rank_form_failures) is unchanged or its pins deliberately updated; current 0.12.x behaviour is characterized first and the pins flipped deliberately; full punk::args suite passes with no expectations weakened; on completion the G-030 -optional 0 workaround sites are revisited (make.tcl dispatch definitions, the src/modules/AGENTS.md "punk::args definition authoring ergonomics" bullet) and relaxed or re-documented.
+
+## Context
+
+Found 2026-07-14 during G-030 (make.tcl dogfooding punk::args). `make.tcl frobnicate`
+under bootsupport punk::args 0.5.0 reported a pointed choiceviolation naming the word
+and the subcommand choices; under 0.12.0 the identical definition reports
+`PUNKARGS VALIDATION {toomanyarguments 1 index 0}` ("Received more values than can be
+assigned to argument names"). Verified by A/B probes that the discriminator is
+`-optional 1` on the choice-restricted argument - NOT -choicegroups membership, NOT
+@form/-synopsis presence, NOT leader-vs-value position (both positions affected).
+
+Worked around in G-030 by declaring the dispatch `subcommand`/`subject` arguments
+`-optional 0` - safe there because the dispatch only parses when a word is present, so
+the required-leader-missing case is unreachable. The workaround is recorded in
+goals/archive/G-030-maketcl-punkargs.md and as an authoring guideline in
+src/modules/AGENTS.md "punk::args definition authoring ergonomics" - both should be
+revisited when this ships.
+
+Assessed mechanism (not yet verified in code): the allocator treats an optional
+argument whose candidate word fails validation as "argument omitted" and moves on;
+when no later slot can consume the word, the final error is the overflow, and the
+earlier, far more informative rejection is discarded. The likely shape of a fix is
+recording candidate rejections during allocation and preferring the most
+specific/nearest one at error-report time - the single-form analogue of the
+multiform rank_form_failures selection.
+
+## Notes
+
+- Related: G-073 (unavailable-choice tailored rejection messages want the same
+  "surface the specific rejection" seam - whichever lands first should leave the
+  other a clean hook), G-071 achieved 2026-07-12 (the optional-element allocation
+  machinery this selection logic sits beside - goals/archive/G-071-punkargs-optional-allocation.md).
+- Archived-goal references in this file: G-030 achieved 2026-07-14 (goals/archive/G-030-maketcl-punkargs.md); G-074 achieved 2026-07-13 (goals/archive/G-074-punkargs-multiform-ambiguity-lint.md).

goals/archive/G-030-maketcl-punkargs.md

@@ -213,8 +213,10 @@ and names ::punkboot::argdoc as an in-tree constructed-def exemplar.
 - The kit-type-mismatch confirmation cannot be triggered without a mismatched
   runtime/target configuration - its -confirm handling is code-reviewed, not
   runtime-proven (the prompt sites share the same policy helper).
-- punk::args error-selection improvement above left to punk::args goals
-  (G-072/G-073 territory) rather than patched mid-goal.
+- punk::args error-selection improvement above left to punk::args goals rather
+  than patched mid-goal - proposed 2026-07-14 as G-082
+  (goals/G-082-punkargs-error-selection.md); the -optional 0 workaround sites
+  here and in src/modules/AGENTS.md are to be revisited when it ships.
 - Old `echo y | make.tcl vfscommonupdate` agent workflow is retired; docs
   updated (src/AGENTS.md, src/tests/shell/AGENTS.md, src/bootsupport/AGENTS.md,
   src/modules/AGENTS.md).

src/modules/AGENTS.md

@@ -344,7 +344,7 @@ Before writing or generating punk::args definitions, know the mechanisms punk::a
 - **`-&` record continuation** (unquoted trailing token) continues a record across lines *inside constructed strings*, where backslash-newline is consumed by the building code's own quoting; brace a literal `{-&}` to escape. Byte-identical assembly to the backslash equivalent.
 - **Container quoting rules** (braced values fully literal; double-quoted values get Tcl backslash semantics with `$`/`[]` still literal; `\$\{...\}` for a literal placeholder) are documented in the `punk::args::define` -help — consult it rather than experimenting.
 - **Script-level/constructed ids want an explicit `@form -synopsis`**: the auto-generated synopsis currently renders the definition id (e.g `(script)::punkboot::modules`), not `@cmd -name` — supply the real invocation string (G-030 lesson).
-- For choice-restricted leaders/values in dispatch-style definitions, prefer `-optional 0` when the calling code only parses when a word is present: as of punk::args 0.12.0 a non-matching word for an *optional* choice arg falls through to a generic overflow error instead of a pointed choiceviolation (regression vs 0.5.0, recorded in goals/archive/G-030-maketcl-punkargs.md).
+- For choice-restricted leaders/values in dispatch-style definitions, prefer `-optional 0` when the calling code only parses when a word is present: as of punk::args 0.12.0 a non-matching word for an *optional* choice arg falls through to a generic overflow error instead of a pointed choiceviolation (regression vs 0.5.0, recorded in goals/archive/G-030-maketcl-punkargs.md; fix proposed as goal G-082 — revisit this guideline when it ships).
 
 ## Verification