G-045 achieved: punk::args 0.8.1 define quoting documentation; flip + archival edits (project 0.12.8)

Increment 5 (final): the container quoting rules pinned by defquoting.test
now appear in the punk::args::define -help documentation - braced values
fully literal (backslash sequences survive as typed); double-quoted values
get Tcl backslash semantics at record parse while $ and [] stay literal
with no substitution outside tstr placeholders; the backslash-escaped
placeholder idiom renders a literal placeholder. Rendered section verified
in punk902z src (meta-escapes display correctly). punk::args suite 186
pass / 1 pre-existing skip / 0 fail.

Acceptance review recorded in the detail file: all criteria satisfied
across increments 1-5 (@cmd -unindentedfields 0.6.1, i help alignment
punk 0.2.4, -& record continuation 0.7.0, @normalize + define_docs
consumer proof 0.8.0/punk 0.2.5, quoting documentation 0.8.1; suite grown
128 -> 187 tests, GAPs flipped, none weakened, full source-tree suite zero
regressions).

Flip edits: G-045 index entry moved to GOALS-archive.md (achieved
2026-07-12), detail file Status flipped with evidence in Progress,
reference sweep updates G-053 notes. The detail file move to
goals/archive/ follows in the next commit as a pure rename (per the
goals/AGENTS.md archive rules) - goals_lint is transiently unclean between
the two.

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

CHANGELOG.md

@@ -5,6 +5,10 @@ The latest `## [X.Y.Z]` header must match the `version` field in `punkproject.to
 Entries are newest-first; one bullet per notable change. See the root `AGENTS.md`
 "Project Versioning" section for the bump policy.
 
+## [0.12.8] - 2026-07-12
+
+- G-045 achieved: punk::args 0.8.1 documents the definition container quoting rules in the punk::args::define help (braced values fully literal; double-quoted values with Tcl backslash semantics at record parse while $ and [] stay literal; the backslash-escaped tstr placeholder idiom). This completes the definition authoring ergonomics goal: @cmd -unindentedfields honoured (0.6.1), -& record continuation (0.7.0), @normalize block-form indent normalization with the help-system definitions as consumer proof (0.8.0 / punk 0.2.5), quoting documentation (0.8.1).
+
 ## [0.12.7] - 2026-07-12
 
 - G-045 (increment): punk::args 0.8.0 adds the bare @normalize directive - opts a definition into indent normalization of block-form multi-line field values (structural leading newline dropped, content re-based to the file-style 4-space continuation convention, relative indents preserved, -unindentedfields exempt, no-op on conforming file-style definitions). Intended for constructed (string-built) definitions. punk 0.2.5: the help-system definitions (::punk::help / help_chunks) convert to indented block authoring under @normalize; 'i help' rendering unchanged.

GOALS-archive.md

@@ -46,6 +46,10 @@ Acceptance: a documented procedure reproduces the spin on the current kit (e.g.
 Scope: src/modules/punk/args-999999.0a1.0.tm (parse + usage rendering), src/modules/punk/ns-999999.0a1.0.tm (cmdinfo/cmd_traverse choice resolution parity), src/modules/punk-999999.0a1.0.tm (punk::help topic argdoc as first consumer), src/tests/modules/punk/args/testsuites/, src/tests/modules/punk/ns/testsuites/
 Acceptance: a definition using -choicealiases parses an alias (and an alias prefix where -choiceprefix allows) to its canonical choice in the parse result, with -choicerestricted 0 passthrough and the deny/reserve lists honoured unchanged; usage display shows one entry per canonical choice with aliases folded (no duplicate rows; -choicelabels attach to the canonical); punk::ns::cmdinfo/cmd_traverse resolve subcommand words to docids with the same outcome as the parser for alias, prefix, denied, reserved and unknown words (the pre-goal characterization tests updated from pinned-GAP to fixed); punk::help's topic definition adopts the feature so `i help` lists one entry per registered topic while `help h`/`help e` still fall through to command lookup; definitions without -choicealiases behave unchanged (existing punk::args and punk::ns suites pass).
 
+### G-045 [achieved 2026-07-12] punk::args definition authoring ergonomics: record continuation, @cmd unindented fields, constructed-definition normalization → detail: goals/archive/G-045-punkargs-authoring-ergonomics.md
+Scope: src/modules/punk/args-999999.0a1.0.tm (record parsing in resolve, tstr interplay, arg_error @cmd rendering), src/tests/modules/punk/args/testsuites/ (rendering.test/defquoting.test as the safety net), src/modules/punk-999999.0a1.0.tm (::punk::helptopic::define_docs de-hacked as the consumer proof)
+Acceptance: a definition using the chosen record-continuation mechanism parses identically to its backslash-continuation equivalent (existing definitions unchanged - continuation is additive), with the token's collision rules documented and an escape/rejection story for values that legitimately match it; @cmd -help/-summary honour -unindentedfields (the rendering.test GAP rendering_unindentedfields_cmd_help_GAP flips to aligned); a constructed definition can request whole-block normalization so embedded continuation indentation behaves as in file-style definitions (the rendering_constructed_def_indent_characterization expectations updated to the chosen semantics), and ::punk::helptopic::define_docs drops its manual pre-normalization to prove it; the quoting rules from defquoting.test appear in the punk::args::define -help documentation; the full punk::args suite (128 tests incl. the rendering invariants: nesting independence, relative-indent preservation) passes with GAP tests flipped, none weakened.
+
 ### G-046 [achieved 2026-07-10] punk::args deferred -help resolution (parse-time performance + reentrancy) and rendering/value-shape fixes → detail: goals/archive/G-046-punkargs-deferred-help-and-fixes.md
 Scope: src/modules/punk/args-999999.0a1.0.tm (resolve/get_dict: display-field deferral, dynamic-cache subst path, prefix writeback, string renderer, cmdhelp-facing messages), src/modules/punk/ansi-999999.0a1.0.tm (mark_columns argdoc as the reentrancy/perf testbed), src/tests/modules/punk/args/testsuites/ (GAP tests flip; perf verification)
 Acceptance: parsing/argument resolution provably skips -help expansion (a definition whose -help contains a ${[...]} that would error or record its invocation shows the substitution did NOT run during a parse-only path, only for help display); first parse of punk::ansi::mark_columns drops from ~4s to well under a second with 'i punk::ansi::mark_columns' still rendering the embedded example, and a -help that parses its OWN definition id resolves or errors cleanly rather than looping; first-parse timing improves for at least one other heavily documented command (recorded in the detail file); rendering_atdynamic_multiline_help_insertion_GAP flips to all-aligned; choicegroups_imap_prefix_listwrap_GAP flips to shape-identical (prefix input yields the same plain string as exact input); the -return string renderer's cmd-help continuations align under the first line with relative indents preserved (rendering_string_renderer_characterization updated); the 'Bad number of leading values...' prefix shown by goodargs parsing in 'i string is'-style output is reworded or suppressed for the usage-display path; full punk::args and punk::ns suites pass with no non-GAP expectations weakened.

GOALS.md

@@ -210,10 +210,6 @@ Detail: goals/G-043-subshell-definition-plugins.md
 Scope: src/modules/punk/repl-999999.0a1.0.tm (editbuf/reader integration, provider seam), src/modules/punk/args-999999.0a1.0.tm + src/modules/punk/ns-999999.0a1.0.tm (introspection surfaces as consumed), src/modules/punk/console-999999.0a1.0.tm (rendering)
 Detail: goals/G-044-repl-command-completion.md
 
-### G-045 [active] punk::args definition authoring ergonomics: record continuation, @cmd unindented fields, constructed-definition normalization
-Scope: src/modules/punk/args-999999.0a1.0.tm (record parsing in resolve, tstr interplay, arg_error @cmd rendering), src/tests/modules/punk/args/testsuites/ (rendering.test/defquoting.test as the safety net), src/modules/punk-999999.0a1.0.tm (::punk::helptopic::define_docs de-hacked as the consumer proof)
-Detail: goals/G-045-punkargs-authoring-ergonomics.md
-
 ### G-047 [proposed] Declared primary VCS in punkproject.toml with per-developer commit-target override
 Scope: punkproject.toml (schema), punkproject.local.toml (new, uncommitted per-checkout override), root AGENTS.md (Commit Conventions (any VCS) section), .gitignore + .fossil-settings/ignore-glob (ignore rules for the local file, per the coexistence contract), src/project_layouts/ (layout template payload - default values and ignore seeding only; project.new validation is follow-on work)
 Detail: goals/G-047-declared-primary-vcs.md

goals/G-045-punkargs-authoring-ergonomics.md

@@ -1,6 +1,6 @@
 # G-045 punk::args definition authoring ergonomics: record continuation, @cmd unindented fields, constructed-definition normalization
 
-Status: active
+Status: achieved 2026-07-12
 Scope: src/modules/punk/args-999999.0a1.0.tm (record parsing in resolve, tstr interplay, arg_error @cmd rendering), src/tests/modules/punk/args/testsuites/ (rendering.test/defquoting.test as the safety net), src/modules/punk-999999.0a1.0.tm (::punk::helptopic::define_docs de-hacked as the consumer proof)
 Goal: authoring punk::args definitions no longer requires backslash line-continuations or ad-hoc workarounds for multi-line records and constructed definitions - a parser-recognised record-continuation mechanism (candidate: an unquoted trailing -& token, with the detail file recording the collision analysis and the element-count disambiguation alternative), -unindentedfields honoured for @cmd fields, and constructed (string-built) definitions able to opt into the same whole-block indent normalization file-style definitions get - with the container quoting rules (braced=literal, quoted=Tcl backslash semantics, \$\{ escape) promoted from defquoting.test into the define documentation.
 Acceptance: a definition using the chosen record-continuation mechanism parses identically to its backslash-continuation equivalent (existing definitions unchanged - continuation is additive), with the token's collision rules documented and an escape/rejection story for values that legitimately match it; @cmd -help/-summary honour -unindentedfields (the rendering.test GAP rendering_unindentedfields_cmd_help_GAP flips to aligned); a constructed definition can request whole-block normalization so embedded continuation indentation behaves as in file-style definitions (the rendering_constructed_def_indent_characterization expectations updated to the chosen semantics), and ::punk::helptopic::define_docs drops its manual pre-normalization to prove it; the quoting rules from defquoting.test appear in the punk::args::define -help documentation; the full punk::args suite (128 tests incl. the rendering invariants: nesting independence, relative-indent preservation) passes with GAP tests flipped, none weakened.
@@ -228,6 +228,36 @@ punk::imap4's {\Deleted}/{$MDNSent} choice values) have them stated, not just te
   regressions; make.tcl modules builds clean; 'i help'/'i help_chunks' verified
   aligned in punk902z src.
 
-Remaining for acceptance:
+### 2026-07-12 increment 5: define quoting documentation (punk::args 0.8.1) - acceptance complete
-- defquoting.test container quoting rules promoted into the punk::args::define
+
-  -help documentation
+- The container quoting rules pinned by defquoting.test now appear in the
+  punk::args::define -help documentation (-help key section): braced values
+  fully literal; double-quoted values with Tcl backslash semantics at record
+  parse ($ and [] literal, no substitution outside tstr placeholders); the
+  backslash-escaped placeholder idiom. Rendered output of the new section
+  verified in punk902z src - the meta-escapes display as intended (\n as two
+  characters, \Deleted, doubled backslash, literal dollar-brace placeholders).
+- punk::args suite 186 pass / 1 pre-existing skip / 0 fail (tclsh 9.0.3).
+
+Acceptance review at flip (2026-07-12): all criteria satisfied.
+- -& record continuation parses identically to its backslash equivalent
+  (recordcontinuation.test byte-equality; additive - existing definitions
+  unchanged); collision rules and the {-&} escape documented (increment 3).
+- @cmd -help/-summary honour -unindentedfields;
+  rendering_unindentedfields_cmd_help_GAP flipped to aligned (increment 1;
+  -summary vacuously honoured - no renderer transforms it, verified).
+- Constructed definitions can request whole-block normalization (@normalize,
+  block-form values); rendering_constructed_def_indent_characterization
+  updated to the chosen opt-in semantics (unopted behaviour pinned as
+  contract); ::punk::helptopic::define_docs dropped its manual
+  pre-normalization - first to interim left-margin authoring (increment 2),
+  then to indented blocks + @normalize as the consumer proof (increment 4).
+- Quoting rules from defquoting.test appear in the define -help documentation
+  (increment 5).
+- Full punk::args suite passes with GAP tests flipped, none weakened: 186
+  pass / 1 pre-existing skip / 0 fail (suite grown from 128 to 187 tests via
+  the new recordcontinuation.test and normalize.test); full source-tree suite
+  showed zero regressions at increments 3 and 4 (exec-14.3 known baseline
+  only). Verified on native tclsh 9.0.3 plus punk902z src for rendered
+  output; punk 0.2.5 / punk::args 0.6.1-0.8.1 shipped in project versions
+  0.12.4-0.12.8.

goals/G-053-punkargs-multiple-ranges.md

@@ -62,8 +62,9 @@ rendering gain meaningful bounded-repetition forms (e.g. "0-1", "2-4").
 
 - `-multipleunique` / `-multipleuniqueset` remain the uniqueness knobs and only
   make sense for max > 1; they compose with ranges unchanged.
-- Related: G-045 (authoring ergonomics), G-046 (parse-time performance - the
+- Related: G-045 (authoring ergonomics, achieved 2026-07-12 - see
-  canonicalization must not regress the hot path).
+  goals/archive/G-045-punkargs-authoring-ergonomics.md), G-046 (parse-time
+  performance - the canonicalization must not regress the hot path).
 - The runtests `-include-paths` fix (repeatable, accumulate, single-list form still
   accepted) shipped independently on 2026-07-10 and does not depend on this goal.
 - Archived-goal references in this file: G-046 achieved 2026-07-10 (goals/archive/G-046-punkargs-deferred-help-and-fixes.md).

punkproject.toml

@@ -1,4 +1,4 @@
 [project]
 name = "punkshell"
-version = "0.12.7"
+version = "0.12.8"
 license = "BSD-2-Clause"

src/modules/punk/args-999999.0a1.0.tm

@@ -1081,10 +1081,26 @@ tcl::namespace::eval punk::args {
                         For the @examples directive this is the text for examples as
                         displayed with 'eg <commandname>'
                         The -help string can be delimited with double quotes or with
-                        curly braces, the choice will affect what inner chars require
+                        curly braces. The container determines the quoting rules,
-                        backslash escaping - but neither type of help block is
+                        which apply to multi-line field values generally:
-                        automatically subject to variable or command substitution aside
+
-                        from those specifically wrapped in placeholders.
+                        Braced {...} values are fully literal: $, [] and backslash
+                        sequences all survive as typed (\\n stays two characters,
+                        and a bare backslash as in \\Deleted keeps its backslash).
+                        Only tstr placeholders (when \$\{...\} content is present
+                        anywhere in the definition block) and their backslash
+                        escape are special.
+
+                        Double-quoted \"...\" values get Tcl backslash semantics
+                        at record parse: \\n becomes a real newline and \\\\
+                        collapses to a single backslash - while $ and [] remain
+                        literal. No variable or command substitution is performed
+                        on record content outside \$\{...\} tstr placeholders.
+
+                        In a tstr-processed block, escaping the placeholder's
+                        dollar sign and braces with backslashes renders a literal
+                        placeholder - the idiom used for the \$\{...\} examples
+                        throughout this help text.
 
                         For cases where unbalanced braces, double quotes are to
                         be displayed to the user without visible backslash escapes,

src/modules/punk/args-buildversion.txt

@@ -1,6 +1,7 @@
-0.8.0
+0.8.1
 #First line must be a semantic version number
 #all other lines are ignored.
+#0.8.1 - G-045 documentation-only: the container quoting rules pinned by defquoting.test promoted into the define -help documentation (-help key section): braced values fully literal (backslash sequences survive as typed) with only tstr placeholders and their backslash escape special; double-quoted values get Tcl backslash semantics at record parse (\n -> newline, doubled backslash collapses) while $ and [] stay literal with no variable/command substitution outside tstr placeholders; the backslash-escaped placeholder idiom renders a literal placeholder.
 #0.8.0 - G-045: new bare @normalize directive - opts a definition into indent normalization of BLOCK-FORM multi-line field values (first line whitespace-only, as authored by opening a braced literal with a newline): the structural first newline and a whitespace-only trailing line are dropped, the content lines' common leading whitespace is the block's base indent, the first content line is unindented fully and subsequent lines re-based to the standard 4-space continuation convention (deeper relative indents preserved; whitespace-only inner lines become empty). Head-form values are never altered - their base indent is ambiguous (uniform continuation indent may be the deliberate +2 relative convention over base 4) - which makes @normalize a no-op on conforming file-style definitions (idempotence pinned). Fields in a record's -unindentedfields are exempt. Implemented as a resolve pre-pass over split records (private::normalize_records / rebase_multiline_value); @normalize with options is an error. Intended for constructed/string-built definitions (no whole-block indent treatment otherwise); ::punk::helptopic::define_docs converts to it as the consumer proof (punk 0.2.5). New testsuite normalize.test; define doc documents the directive; rendering.test P4 notes stay pinned as the unopted default.
 #0.7.0 - G-045: record-continuation token -& - an unquoted trailing -& element on a definition record line continues the record on the next line. Implemented in private::split_definition_records: the token is dropped and the next line joins after a single space with its leading whitespace collapsed, exactly how the Tcl parser joins backslash-newline continuations before a braced definition reaches the splitter - so a -& record assembles byte-identical to its backslash-continued equivalent (proven by parse+render equality test). Motivation: constructed/string-built definitions cannot author backslash-newline ergonomically (the building code's own quoting consumes it); -& is plain text and survives any construction. Collision rules: the token must be a bare word preceded by whitespace (or the whole line), trailing whitespace after it is tolerated (more forgiving than raw backslash-newline); a braced/quoted -& is data ({-&} is the escape for a literal trailing value); -& mid-line, -& as a word suffix (abc-&), and -& on lines inside still-open braced/quoted values are all data. Backslash continuation authoring is unchanged (continuation is additive). New testsuite recordcontinuation.test; define doc documents the token alongside backslash continuation.
 #0.6.1 - G-045: @cmd honours -unindentedfields for -help - arg_error's display-time indent transform (undent "    "+help, max 4) is now gated by "-help" membership in the @cmd line's -unindentedfields list (same gate argument -help already had), so left-margin-authored cmd help renders its first line flush with continuations in both the table and string renderers. Previously the option was accepted on @cmd but ignored (rendering.test rendering_unindentedfields_cmd_help_GAP - flipped to rendering_unindentedfields_cmd_help). No in-tree definitions set @cmd -unindentedfields, so existing rendering is unchanged. Note: @cmd -summary has no indent transform in any renderer, so -unindentedfields membership for -summary is accepted and vacuously honoured. define doc for -unindentedfields now states where the option is valid.