From 590b09d38c36d482b11bcba666f56f9c1b6daf86 Mon Sep 17 00:00:00 2001 From: Julian Noble Date: Sun, 12 Jul 2026 19:26:15 +1000 Subject: [PATCH] goals: G-045 record define_docs end-state decision (indented-plus-normalized) User decision 2026-07-12: when the constructed-definition normalization mechanism lands, define_docs converts from its interim left-margin authoring to indented-plus-normalized authoring, remaining the acceptance criterion's consumer proof as written. Left-margin authoring via -unindentedfields stays a supported style proven by the rendering tests, but is not the preferred style for define_docs itself. Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com --- goals/G-045-punkargs-authoring-ergonomics.md | 18 ++++++++++-------- 1 file changed, 10 insertions(+), 8 deletions(-) diff --git a/goals/G-045-punkargs-authoring-ergonomics.md b/goals/G-045-punkargs-authoring-ergonomics.md index 056ea982..01a861a2 100644 --- a/goals/G-045-punkargs-authoring-ergonomics.md +++ b/goals/G-045-punkargs-authoring-ergonomics.md @@ -127,19 +127,21 @@ punk::imap4's {\Deleted}/{$MDNSent} choice values) have them stated, not just te block's +12 continuation leak and the topic Help first-line +4 are both gone; 'i help' renders flush end-to-end. punk::ns suite 53/53; make.tcl modules clean. -- Planning note: the constructed-def normalization increment's consumer proof - was to be define_docs "dropping manual pre-normalization". define_docs now - uses the documented -unindentedfields idiom (left-margin authoring), not a - hack - when normalization lands, either define_docs converts to - indented-plus-normalized authoring (likely nicer in a builder proc) or - ensemble_subcommands_definition serves as the proof; decide and record then. +- Decision (user, 2026-07-12): when the constructed-def normalization mechanism + lands, define_docs converts from its interim left-margin authoring to + indented-plus-normalized authoring - it remains the acceptance's consumer + proof as written. Left-margin authoring via -unindentedfields stays a + supported style proven by tests (rendering_unindentedfields_arg_help, + rendering_unindentedfields_cmd_help), but it is not the preferred style for + define_docs itself. Remaining for acceptance: - record-continuation mechanism (the -& candidate): collision rules, escape story, parses identically to backslash-continuation equivalent, documented - constructed-definition whole-block normalization opt-in, with rendering_constructed_def_indent_characterization expectations updated and - a constructed-def consumer converted as proof (see increment 2 planning note - on define_docs vs ensemble_subcommands_definition) + ::punk::helptopic::define_docs converted from interim left-margin authoring + to indented-plus-normalized as the consumer proof (user decision 2026-07-12, + see increment 2 notes) - defquoting.test container quoting rules promoted into the punk::args::define -help documentation