From 055f4bbf2ff10c1a40a44ecbec5f6036b0b286d9 Mon Sep 17 00:00:00 2001
From: Julian Noble <julian@precisium.com.au>
Date: Fri, 7 Aug 2026 14:35:01 +1000
Subject: [PATCH] G-083 increment 1: punk::args argument-relations define-time
 vocabulary (0.19.0)

Spec compiler (resolve) accepts and stores the new relation keys:
- per-argument -conflicts <list>: parsekeys or flag names that must not be
  RECEIVED together with this argument; checked against received args only at
  parse time (defaults never conflict) - parse-time optionconflict enforcement
  lands in a later G-083 increment.
- @opts-level -parsekeymode override|error: per named OPT_GROUPS group; error
  = distinct-member co-occurrence within a shared-parsekey group raises
  optionconflict at parse; override = legacy last-wins, the default.

Both keys are cross-validated at resolve: -conflicts targets must name a defined
argname or declared -parsekey; -parsekeymode requires -group and a value of
override|error. Define-time integrity hole closed: a -parsekey colliding with a
distinct defined argument's name (one not sharing that -parsekey) is now a
resolve error instead of silently forming an implicit shared-key group
(parsekey_collides_with_defined_optname_GAP flipped in parsekey.test to a
define-time error pin, plus redundant-self-name and deliberate-shared-group
guards).

Design settled (recorded in the goal detail): -parsekeymode is per named group
(OPT_GROUPS entry, keyed by the @opts line's -group), not form-wide. Rationale:
lsearch uses per-arg -conflicts only (partial conflicts, groups stay default
override); clock clicks uses -parsekeymode error on its single named group
(full pairwise exclusivity). Unnamed shared-parsekey groups default override.

Legacy untouched by default: -parsekeymode override is the default and absent
-conflicts means no check runs; the pinned parsekey_repeat_ordering last-wins /
prepend-defaults idiom and the full existing suite pass unchanged.

New testsuite relations.test pins the define-time vocabulary (7 tests, matching
the longopts.test/mashopts.test error-pin style). buildversion 0.18.0 -> 0.19.0.

Verification: full punk/args suite via canonical tclsh90s - 356 total / 353
passed / 3 skipped (punkargsKnownBug) / 0 failed. goals_lint clean. No
punkproject.toml bump (define-time only; no shell-level user-visible behaviour
yet - the module change, not the shell product).

Assisted-by: harness=pi; primary-model=huggingface/zai-org/GLM-5.2; api-location=huggingface.co
---
 goals/G-083-punkargs-argument-relations.md    |  28 +++++
 src/modules/punk/args-999999.0a1.0.tm         |  84 ++++++++++++-
 src/modules/punk/args-buildversion.txt        |   3 +-
 src/tests/modules/AGENTS.md                   |   2 +-
 .../punk/args/testsuites/args/parsekey.test   |  30 +++--
 .../punk/args/testsuites/args/relations.test  | 116 ++++++++++++++++++
 6 files changed, 243 insertions(+), 20 deletions(-)
 create mode 100644 src/tests/modules/punk/args/testsuites/args/relations.test

diff --git a/goals/G-083-punkargs-argument-relations.md b/goals/G-083-punkargs-argument-relations.md
index 836fce22..2ab771e7 100644
--- a/goals/G-083-punkargs-argument-relations.md
+++ b/goals/G-083-punkargs-argument-relations.md
@@ -84,3 +84,31 @@ Design leans (settle and record here during the work):
 - Related: G-053 (occurrence arity), G-072 (compound clause types - orthogonal),
   G-084 (parsekey completeness fixes; its cross-member -multiple design
   decision should be made with this goal's vocabulary in mind).
+
+## Progress
+
+- 2026-08-07 increment 1 (define-time vocabulary, punk::args 0.19.0): spec compiler
+  accepts and stores the new keys - per-arg `-conflicts <list>` (ARG_INFO) and
+  @opts-level `-parsekeymode override|error` (per named OPT_GROUPS entry, default
+  override). Resolve cross-validates: `-conflicts` targets must name a defined
+  argname or declared `-parsekey`; `-parsekeymode` requires `-group` and a value of
+  override|error. Define-time integrity hole closed: a `-parsekey` colliding with a
+  distinct defined argument's name (one not sharing that `-parsekey`) is now a
+  resolve error instead of silently forming an implicit shared-key group
+  (parsekey_collides_with_defined_optname_GAP flipped in parsekey.test to a
+  define-time error pin). No parse-time enforcement yet - the optionconflict raise
+  and parse_status_classify entry are increment 2. New testsuite relations.test pins
+  the define-time vocabulary (7 tests). Legacy untouched by default confirmed: full
+  punk/args suite 356 total / 353 passed / 3 skipped (punkargsKnownBug) / 0 failed
+  via tclsh90s.
+  - Design decision settled: `-parsekeymode` is per named group (OPT_GROUPS entry,
+    keyed by the @opts line's `-group`), not form-wide. Rationale: lsearch has
+    three shared-parsekey groups and uses per-arg `-conflicts` only (partial
+    conflicts within/across groups, all groups stay default override); clock
+    clicks uses `-parsekeymode error` on its single named group (full pairwise
+    exclusivity). Both adoption cases use named groups. Unnamed shared-parsekey
+    groups default to override (a user wanting strict adds `-group`).
+  - Remains for acceptance: increment 2 (parse-time optionconflict raise in the
+    shared post-resolution block, mash+ordinary parity, parse_status_classify);
+    increment 3 (synopsis/usage hints for conflicts/parsekeymode; lsearch + clock
+    clicks moduledoc adoption and dropping the caveat).
diff --git a/src/modules/punk/args-999999.0a1.0.tm b/src/modules/punk/args-999999.0a1.0.tm
index 40567c08..a8ec83bc 100644
--- a/src/modules/punk/args-999999.0a1.0.tm
+++ b/src/modules/punk/args-999999.0a1.0.tm
@@ -2659,7 +2659,7 @@ tcl::namespace::eval punk::args {
                                     -group {
                                         tcl::dict::set tmp_optspec_defaults -group $v
                                         if {$v ne "" && ![tcl::dict::exists $FDICT OPT_GROUPS $v]} {
-                                            tcl::dict::set FDICT OPT_GROUPS $v {-parsekey {} -help {}}
+                                            tcl::dict::set FDICT OPT_GROUPS $v {-parsekey {} -help {} -parsekeymode override}
                                         }
                                         if {$v ne ""} {
                                             if {[tcl::dict::exists $at_specs -parsekey]} {
@@ -2678,15 +2678,37 @@ tcl::namespace::eval punk::args {
                                         set groupdict [tcl::dict::get $FDICT OPT_GROUPS]
                                         #set helprecords [tcl::dict::get $F $fid OPT_GROUPS_HELP]
                                         if {![tcl::dict::exists $groupdict $g]} {
-                                            tcl::dict::set FDICT OPT_GROUPS $g [dict create -parsekey {} -help $v]
+                                            tcl::dict::set FDICT OPT_GROUPS $g [dict create -parsekey {} -help $v -parsekeymode override]
                                         } else {
                                             tcl::dict::set FDICT OPT_GROUPS $g -help $v
                                         }
                                     }
+                                    -parsekeymode {
+                                        #G-083: @opts-level strict mode for a shared-parsekey group.
+                                        #override (default) = legacy last-wins among distinct members sharing the parsekey.
+                                        #error = distinct-member co-occurrence within the group raises optionconflict at parse.
+                                        #Applies to the group named by this @opts line's -group (and its -parsekey);
+                                        #-group is required when -parsekeymode is given so the target group is named.
+                                        if {$v ne "override" && $v ne "error"} {
+                                            error "punk::args::resolve Bad @opt line. -parsekeymode must be 'override' or 'error'. got '$v' @id:$DEF_definition_id"
+                                        }
+                                        if {![tcl::dict::exists $at_specs -group]} {
+                                            error "punk::args::resolve Bad @opt line. -parsekeymode requires -group to name the shared-parsekey group it applies to. @id:$DEF_definition_id"
+                                        }
+                                        set g [tcl::dict::get $at_specs -group]
+                                        if {$g eq ""} {
+                                            error "punk::args::resolve Bad @opt line. -parsekeymode requires a non-empty -group to name the shared-parsekey group it applies to. @id:$DEF_definition_id"
+                                        }
+                                        if {![tcl::dict::exists [tcl::dict::get $FDICT OPT_GROUPS] $g]} {
+                                            tcl::dict::set FDICT OPT_GROUPS $g [dict create -parsekey {} -help {} -parsekeymode $v]
+                                        } else {
+                                            tcl::dict::set FDICT OPT_GROUPS $g -parsekeymode $v
+                                        }
+                                    }
                                     -range {
                                         if {[dict exists $at_specs -type]} {
                                             set tp [dict get $at_specs -type]
-                                        } else {
+        } else {
                                             set tp [dict get $tmp_optspec_defaults -type]
                                         }
                                         if {[llength $tp] == 1} {
@@ -2728,7 +2750,7 @@ tcl::namespace::eval punk::args {
                                         tcl::dict::set tmp_optspec_defaults $k $v
                                     }
                                     default {
-                                        set known   {   -parsekey -group -grouphelp
+                                        set known   {   -parsekey -group -grouphelp -parsekeymode
                                                         -any -anyopts -mash -arbitrary -form -minsize -maxsize -choices -choicegroups -choicemultiple -choicecolumns -choicelabels -choiceinfo
                                                         -type -range -typeranges -default -defaultdisplaytype -typedefaults
                                                         -choiceprefix -choiceprefixdenylist -choiceprefixreservelist -choicerestricted -nocase
@@ -3376,6 +3398,17 @@ tcl::namespace::eval punk::args {
                         -parsekey - -group {
                             tcl::dict::set spec_merged $spec $specval
                         }
+                        -conflicts {
+                            #G-083: per-argument relation. A list of parsekeys or flag names that
+                            #must not be RECEIVED together with this argument. Checked against
+                            #received arguments only (defaults never conflict); resolved through
+                            #the alias/prefix machinery at check time. Cross-validated against
+                            #the defined argument set after all specs merge.
+                            if {[catch {llength $specval}]} {
+                                error "punk::args::resolve - invalid value for key '$spec' in specifications for argument '$argname' - value must be a list of parsekeys or flag names @id:$DEF_definition_id"
+                            }
+                            tcl::dict::set spec_merged -conflicts $specval
+                        }
                         -mash {
                             #allow when any alt in argname is a single letter flag such s -a or -Z
                             #single letter flags do not have to be -type none to allow -mash to be set true.
@@ -3533,7 +3566,7 @@ tcl::namespace::eval punk::args {
                             } else {
                                 set known_argopts [list {*}{
                                                     -form -type
-                                                    -parsekey -group
+                                                    -parsekey -group -conflicts
                                                     -range -typeranges
                                                     -default -defaultdisplaytype -typedefaults
                                                     -minsize -maxsize -choices -choicegroups
@@ -3740,6 +3773,47 @@ tcl::namespace::eval punk::args {
                 }
             }
 
+            #G-083: define-time integrity for -parsekey and the new relations vocabulary.
+            #Cross-arg checks run here because all ARG_INFO entries for the form exist by now.
+            set _g83_argnames [dict get $FDICT OPT_NAMES]
+            lappend _g83_argnames {*}[dict get $FDICT VAL_NAMES]
+            lappend _g83_argnames {*}[dict get $FDICT LEADER_NAMES]
+
+            #(a) -parsekey colliding with a distinct defined arg's name silently forms an
+            #implicit shared-key group (parsekey_collides_with_defined_optname_GAP). Reject
+            #unless that other arg also declares the same -parsekey (a deliberate group).
+            foreach _g83_an $_g83_argnames {
+                set _g83_pk [punk::args::system::Dict_getdef [dict get $FDICT ARG_INFO $_g83_an] -parsekey ""]
+                if {$_g83_pk eq ""} continue
+                foreach _g83_other $_g83_argnames {
+                    if {$_g83_other eq $_g83_an} continue
+                    if {$_g83_other ne $_g83_pk} continue
+                    set _g83_other_pk [punk::args::system::Dict_getdef [dict get $FDICT ARG_INFO $_g83_other] -parsekey ""]
+                    if {$_g83_other_pk ne $_g83_pk} {
+                        error "punk::args::resolve - -parsekey '$_g83_pk' for argument '$_g83_an' collides with the name of defined argument '$_g83_other' (which does not share that -parsekey). Use a distinct -parsekey, or give '$_g83_other' the same -parsekey to form an explicit shared-key group. @id:$DEF_definition_id"
+                    }
+                }
+            }
+
+            #(b) -conflicts targets must name a defined argname or a declared -parsekey.
+            #(the alias/prefix resolution of received args happens at parse time.)
+            set _g83_resolve_targets [dict create]
+            foreach _g83_t $_g83_argnames {
+                dict set _g83_resolve_targets $_g83_t 1
+                set _g83_tpk [punk::args::system::Dict_getdef [dict get $FDICT ARG_INFO $_g83_t] -parsekey ""]
+                if {$_g83_tpk ne ""} {dict set _g83_resolve_targets $_g83_tpk 1}
+            }
+            foreach _g83_an $_g83_argnames {
+                set _g83_conflicts [punk::args::system::Dict_getdef [dict get $FDICT ARG_INFO $_g83_an] -conflicts {}]
+                if {![llength $_g83_conflicts]} continue
+                foreach _g83_target $_g83_conflicts {
+                    if {![dict exists $_g83_resolve_targets $_g83_target]} {
+                        error "punk::args::resolve - -conflicts for argument '$_g83_an' names '$_g83_target' which is neither a defined argument name nor a declared -parsekey in this form. @id:$DEF_definition_id"
+                    }
+                }
+            }
+            unset -nocomplain _g83_argnames _g83_resolve_targets _g83_an _g83_pk _g83_other _g83_other_pk _g83_t _g83_tpk _g83_conflicts _g83_target
+
             #set mashargs [dict get $F $fid OPT_MASHES]
             set mashargs [dict get $FDICT OPT_MASHES]
             if {[llength $mashargs]} {
diff --git a/src/modules/punk/args-buildversion.txt b/src/modules/punk/args-buildversion.txt
index 10096581..4a9b79aa 100644
--- a/src/modules/punk/args-buildversion.txt
+++ b/src/modules/punk/args-buildversion.txt
@@ -1,6 +1,7 @@
-0.18.0
+0.19.0
 #First line must be a semantic version number
 #all other lines are ignored.
+#0.19.0 - G-083 increment 1 (argument-relations define-time vocabulary): new per-argument key -conflicts <list> (parsekeys or flag names that must not be RECEIVED together with this argument; checked against received args only at parse time, defaults never conflict - parse-time optionconflict enforcement lands in a later G-083 increment) and new @opts-level -parsekeymode override|error (per named OPT_GROUPS group; error = distinct-member co-occurrence within a shared-parsekey group raises optionconflict at parse; override = legacy last-wins, the default). Both keys are cross-validated at resolve: -conflicts targets must name a defined argname or declared -parsekey; -parsekeymode requires -group and a value of override|error. Define-time integrity hole closed: a -parsekey value colliding with a distinct defined argument's name (one that does not share that -parsekey) is now a resolve error instead of silently forming an implicit shared-key group (parsekey_collides_with_defined_optname_GAP flipped to a define-time error pin in parsekey.test). Legacy behaviour untouched by default (no -conflicts, default -parsekeymode override, no colliding parsekey). New testsuite relations.test pins the define-time vocabulary; full punk/args suite green.
 #0.18.0 - G-151 annotated success render: new punk::args::parse_report - landing report for a SUCCESSFUL parse, one row per value-holding argument (received, or filled from -default) in declaration-section order (leaders, opts, values) with columns Argument | Source | Value - the success-side sibling of the arg_error usage table (a flag-like word consumed as a VALUE by position shows attributed to its consuming argument - the make.tcl dry-run 'kitname = punk91 -confirm 0' class). Input: a punk::args::parse result dict (its id key must resolve to a registered definition), or words + 'withid <id>' (the parse is performed first; a rejected line raises the same validation error parse would - only successful parses have a landing report). Source column: received / received xN (-multiple aggregation count) / default - the plain-mode-safe twin of the colour marking (received CLR(check), default CLR(parsekey_hint)); absent optionals with no default-in-effect get no row. Returns: table (arg_error-styled bordered block via textblock; the default), tableobject, string (plain lines 'name (source) = value'; also the degraded no-textblock path), dict (machine form: id/form/rows with class/source/received/positions/multiple/hasvalue/value - never elided). Display elision is type-aware, deterministic and always marked (display-hint honesty): strings single-line-ized (ansistring VIEW -lf 1 -vt 1 -sp 0 - embedded controls/ANSI render visibly so a value cannot disturb the table; real spaces stay spaces) then grapheme-capped via the new ansistring TRUNCATE (punk::ansi 0.2.0) with trailing '...' plus ' (len N)' citing the raw value's string length; -multiple aggregations and -type list values element-capped with '(+N more)' (whole list-quoted elements kept while they fit, first element char-capped if it alone overflows); -type dict values pair-capped with '(+N pairs)'; markers stay intact so cells can exceed very small caps by the marker width; plain-string fallbacks when punk::ansi is unavailable. Width cascade per the G-149 plumbing precedent: caller -valuewidth > new @cmd directive key -reportvaluewidth > built-in 48; 0 means no cap; deliberately never console-derived (deterministic and pipe-safe - the G-007 emit-then-query lesson). Value-in-effect lookup bridges storage-key folds at display level (-parsekey renames, aliased optionsets' last-|-member finalopts fold) so received aliased/parsekey'd arguments keep their row - G-084 owns the storage-key model itself. Failure-side rendering (arg_error/usage) unchanged. make.tcl retiring its interim one-line 'dry-run: line accepted ...' report in favour of this render is consumer follow-through after a bootsupport promotion (not part of this change). New testsuite parsereport.test; define -help documents @cmd -reportvaluewidth beside the other directive-options.
 #0.17.0 - G-149 configurable multi-form synopsis hint labels: the per-form hint labels rendered beside a multi-form definition's synopsis lines in the usage/arg_error table (hard-coded ' i -form N ...' previously) are now a template substituted per form - %formindex% replaced with the form's 0-based ordinal, %formname% with its name; an empty template suppresses the labels entirely (the cell keeps just the Synopsis: label, as single-form renders do). Precedence: caller option > definition > built-in default. New arg_error/usage option -formhint <template> (supplied-empty means suppress; usage pulls it from arg_error's definition via resolved_def); new @cmd directive key -formhint <template> for definition-supplied hints (rides the existing arbitrary-key cmd_info merge, so resolved_def round-trips it; not display-deferred). Unconfigured definitions render byte-identical to 0.16.0 (default template reproduces the exact prior bytes, verified by capture diff). Motivation (G-143 origin): script-level (script) ids - e.g make.tcl's - are unreachable from any repl, so the repl-oriented ' i -form N ...' default is not actionable there; consumers can now name their own per-form navigation. The string (non-table) renderer never carried hint labels and is unchanged. make.tcl adoption is consumer follow-through after a bootsupport promotion (not part of this change). New testsuite formhint.test; define -help documents the @cmd key beside the other directive-options.
 #0.16.0 - G-073 unavailable choices: new per-argument key -choiceunavailable <list> - names that are recognised but not available in the current runtime/context. Display: entries render among the choices under a dedicated 'Unavailable (recognised, not selectable here)' group heading (table title / string-renderer Group heading - the distinguishing mechanism) with their ordinary -choicelabels notes, and join the prefix-calculation pool (display shortest-prefix marking reflects their reserving effect); synopsis choice-literal display and value-in-effect/goodarg marking never include them (structural: they are not in -choices/-choicegroups, and -default may not name one). Parse: choiceword_match gains an optional 8th argument unavailablelist and an 'unavailable' result key - a word landing on an unavailable name (exact, or unique prefix; case per -nocase) reports unavailable 1 with the name as canonical while matched stays 0, so matched-only consumers treat it as an ordinary non-match; a prefix shared between an available and an unavailable name is a plain ambiguous non-match. Validation rejects such a landing with the tailored PUNKARGS VALIDATION {choiceunavailable <name> choices <list>} error (-badarg/-badval; message names the entry, its -choicelabels note - e.g a version boundary - and the available values; private::unavailable_choice_msg shared by all raise surfaces). The G-071 allocation screen honours the list (optional-arg landings recorded as G-082 rejection kind 'unavailable' and preferred at the overflow raise sites); required args are unscreened as before, so their landing reports via final validation identically. Ambiguous-prefix messages annotate unavailable longer matches '(recognised but unavailable)'. -choicerestricted 0 keeps full passthrough (no tailored rejection). Resolve-time validation: requires -choices/-choicegroups; entries must not collide with choices, -choicealiases alias names, or -choiceprefixreservelist entries; -default may not be an unavailable name. form_literal_affinity/formcheck screens pass the list through (uniform pool semantics). In-tree adopter: punk::args::moduledoc::tclcore 'string is' forward classes (dict on 8.6). New testsuite choiceunavailable.test; tclcoreparity.test gains forward-class pins + the user-sanctioned 'di' strictness exemption; define -help documents the key.
diff --git a/src/tests/modules/AGENTS.md b/src/tests/modules/AGENTS.md
index c3ce2956..033ca5f2 100644
--- a/src/tests/modules/AGENTS.md
+++ b/src/tests/modules/AGENTS.md
@@ -43,7 +43,7 @@ Unit tests for editable source modules under `src/modules/`, `src/modules_tcl8/`
 - `commandstack/` — commandstack (cooperative command renaming) tests (`testsuites/commandstack/commandstack.test`, 2026-08-03 - characterisation suite + the G-160 hygiene-pass contract at commandstack 0.6.0 + the 0.7.0 convenience removal forms + the 0.7.1 reload-contract state guards (G-160 follow-ons, 2026-08-04); usage-driven from punk::packagepreference/packagetrace/packagesuppress/punk-auto_execok/punk::nav::fs-cd): record shape as a contract (token first/renamer second dict key order for the lsearch -index 1/-index 3 convention, trailing `did_rename` 0|1, `{implementation {} did_rename 0}` no-rename signal), COMMANDSTACKNEXT/COMMANDSTACKNEXT_ORIGINAL delegation + the `commandstack::next` helper (caller-context parity with the manual uplevel convention pinned), unique+monotonic per-(renamer,command) tokenids (same-renamer re-renames chain and are removable by exact token, third rename succeeds), multi-renamer stacking with removal in any order (bottom-removal re-linking), builtin renames (next_implementor `original`), remove_rename's three argument forms + unknown-renamer errors, the 0.7.0 convenience removal forms (pop_rename - command form pops topmost-for-renamer and returns the removed record, bare form searches live stacks with a multi-command ambiguity error; remove_renamer - all of a renamer's entries across live stacks with correct re-linking, Rename_stack-parked stacks skipped, removed records returned keyed by command; restore_original - whole-stack unwind to the original returning the record count, deliberately registering stack-evidenced renamers so it survives a known_renamers reset while the renamer-explicit forms keep the gate; all silent with debug off), the token->implementation map get_next_command resolves through (map/stack consistency pinned across rename/remove; parked stacks keep dispatching), channel discipline (silent full cycle with debug off; warnings only under debug), debug argument validation, -renamer misplacement errors, get_stack raw-key-first retrieval of Rename_stack-parked records + Rename_stack 1/0 returns, Delete_stack live-record guard (errors; empty/missing return 1), get_IMPLEMENTOR classification incl builtin-where-cmdtype-exists (dynamic expectation - undetermined on 8.6), lib::split_body round-trip, lib::splitx, show_stack fallback render, the reload contract (a module re-source preserves ALL state - stacks/token counters/token map/known_renamers/debug each info-exists guarded; delegation and exact-token removal keep working after reload), the help overview, and lazy punk::args registration of the PUNKARGS docs. Behavioural tests run in fresh child interps per test (module sourced by path relative to the test file; a ::puts shim captures module output for silence/warning assertions and keeps runner output clean); descriptions are single-line per the tcltestrun banner-parsing style guidance in src/tests/AGENTS.md (a hard contract until G-161 made the parser multi-line tolerant). Green on tclsh90 (9.0.3) and punk86 (8.6)
 - `punkcheck/` — punkcheck module tests (install, summarize_install_resultdict, installtrack)
 - `punk/ansi/` — punk::ansi tests (`testsuites/ansi/`): ansistrip/ansimerge, plus characterization of the ANSI-at-position mechanisms (`ansistring.test`: INDEX/INDEXCODE/INDEXCHAR/RANGE/INSERT grapheme indexing with SGR-prefix merging, INDEXCOLUMNS/COLUMNINDEX double-wide column mapping, trim/VIEW; extended 2026-08-05 by the G-151 pre-modification coverage survey - VIEW -lf 0/1/2 single-line-ization modes + always-on NUL + silent unknown-option tolerance (load-bearing for overtype's '-nul 1' sites) + C1/zero-width visuals, RANGE end-relative/clamping plus the merged-code-stack re-emission and trailing-code-drop semantics a truncate primitive must respect, COUNT-vs-length combining-accent divergence, NEW object basics, and the KNOWN-DEFICIENCY pin that VIEWCODES/VIEWSTYLE raise invalid-command in a plain punk::ansi interp (bare 'a+'/'a' interactive-alias dependency; pinned in a fresh child interp); plus the TRUNCATE primitive pins landed with G-151 (punk::ansi 0.2.0) - fits-unchanged byte identity incl styled fixtures, grapheme-exact capping with marker budget participation and marker-alone truncation, SGR-reset-before-marker on styled prefixes, CJK/combining-cluster grapheme safety, and strict option errors (deliberately unlike VIEW's pinned silent tolerance)), code splitting invariants (`ta.test`: detect/detectcode distinction, split_codes/split_codes_single/split_at_codes shapes and round-trip) and single-code/effective-state semantics (`codetype.test`: is_sgr_reset/has_sgr_leadingreset, has_any/all_effective, sgr_merge, sequence_type classify), grepstr characterization (`grepstr.test`: return modes incl summarydict (linemap pinned as always-present - the -help says -n-only, reconciliation deferred to the planned hygiene pass), exact highlight SGR wrapping, -n line numbering, invert + empty-highlight strip, -C context/breaks, capture groups, and the tab deficiency: warns once per call on stderr, single-pass tab line survives - the multi-pass mangling is pinned at consumer level in punk/ns corp.test), and untabify characterization (`untabify.test`: -stops int/list/terminal, -with spaces/unicode/custom-pair, multiline, errors, plus the EXPERIMENTAL -plastic elastic-tabstop mode deliberately pinned-as-interim and retained for possible repl editbuf use). Console queries (get_tabstops/get_size + punk::console::tabwidth) are mocked per the overtype renderline.test pattern - they emit live terminal queries that block/error headless. ANSI codes in these tests are literal escape strings so results are colour-state independent
-- `punk/args/` — punk::args tests (`testsuites/args/`): parsing, choices/choicegroups, forms (incl the 2026-08-05 candidacy fencing/fall-through primitive pins ahead of G-168: -regexprefail on optional value slots is form-fatal with no re-landing, unknown-option/dangling-option/option-value-fence failures fall through to sibling forms as successful parses, and the documented per-word limit - a complete option+value+file line double-matches a fenced scriptfile form and a dash-tolerant stdin form), registered-namespace lazy definition loading (`docpackages.test`, G-169 pre-work: inert registration/scan-vs-load split, id_exists never triggers loading, real_id/usage lazy resolution incl tag-prefixed script-level id families, duplicate-definer last-loaded-wins characterization), the G-168 launch-definition model parity (`punkexemodel.test`, punkexe moduledoc 0.7.0, id loading updated for the G-169 handover - the script id resolves via app-punkscript-docs from src/lib (auto_path derived from the test file location) while the moduledoc carries the core-owned ids: script/tclsh selection matrices against the real (script)::punkexe ids with the real-side dispatch/app oracle recorded in goals/archive/G-168, the bare-'-e' viable-incomplete verdict, the ./-e fence message, -encoding fall-through statuses, and the sanctioned complete-'-encoding' multipleformmatches LIMIT pins; the formcheck.test punkexe GAPs flipped to discriminated/sanctioned/selection-sound pins in the same arc), the G-151 landing report (`parsereport.test`, punk::args 0.18.0 parse_report: the canonical flag-like-word-consumed-as-VALUE attribution row, parsed-result vs words+withid entry parity, machine dict shape with declaration-section row order and absent-optional row omission, received xN multiplicity for solos/-multiple opts, type-aware always-marked elision at the default width plus the caller > @cmd -reportvaluewidth > built-in width cascade and never-elided dict returns, VIEW-style single-line-ization of control-bearing values, aliased-optionset storage-key row bridging, bordered-table/tableobject renders, words-form failure errorcode parity with parse, and the registered two-form definition's own render), rendering/indentation characterization, synopsis display characterization (`synopsis.test`: basic italic argname/`<type>` styling, longopt `--x=` alias forms, literal/literalprefix/stringstartswith/stringendswith type-alternates rendering unitalicised, option alternate parenthesization, multi-element clause display incl `?type?` members and argname tail-word hints, `-typesynopsis` value-element lists and option passthrough incl documenter ANSI, and the small-restricted-choice-set literal rule: 1-3 restricted choices render as unitalicised `|`-joined literals in leader/option/value positions with choicegroups counted, >3 or `-choicerestricted 0` falling back to italics, `-typesynopsis` taking precedence), usage-marking characterization (`usagemarking.test`: -parsedargs/-badarg/-parsestatus/-scheme marking primitives plus goodchoice highlighting of selected/default-in-effect choice words, asserted by SGR-parameter subset against the live colour arrays; the G-049 nocolour/colour-leak GAP pins flipped 2026-07-10 to scheme-statelessness assertions), the G-049 parse-status structure (`parsestatus.test`: punk::args::parse_status overall/per-argument statuses, badarg for type/allocation failures, -caller attribution, errorcode -argspecs stripping), -parsekey characterization (`parsekey.test`: result/received/solos/multis keying, shared-key required satisfaction and defaults, mash-path and prefix-abbreviation keying, plus GAP pins for last-defined-member default precedence, cross-member -multiple value loss, parsekey/optname collision conflation, and values/leaders parsekey breakage - desired-behaviour pins disabled behind punkargsKnownBug in `testsuites/dev/parsekey-knownbugs.test`), longopt style-distinction and mash-edge characterisation (`longopts.test`, 2026-08-07 gap-fill: the gnu (`--flag=` inline-only; spaced/solo usage = badoptionformat) vs plain (`--flag` spaced-only; inline `=` = invalidoption) vs mixed (`-f|--file|--file=` both forms incl longopt prefix abbreviation) definition-grammar distinctions, first-`=`-only value splitting and empty inline values, the two `=`-member resolve-time definition errors, single-dash `-flag=value` never split at the `=`, and `@opts -any 1` adhoc passthrough where `--flag=value` splits but `-flag=value` stays a whole adhoc flagname expecting a value; the same gap-fill added to `mashopts.test`: unknown-letter-in-mash invalidoption rejection and the `-any` interplay - defined flags still mash while undefined mash-lookalike tokens are adhoc flags, never mash attempts; error-shape pins use the first three -errorcode elements), and tclcore doc/interpreter behavioural parity (`tclcoreparity.test`, G-054, gated on have_tclcoredocs: 'string is' class choices equal the live-harvested set, per-class docids exist, error-vs-ok agreement across the probe matrix; version-note labels appear when the class is live OR is a declared forward unavailable class - dict labels on every runtime since G-073, unicode keeps the live-only rule; the G-073 forward-class adoption invariants and the USER-SANCTIONED 'di' prefix-strictness exemption (the model is deliberately stricter than real 8.6, full words parity-true); and the G-166 pin that an unavailable class's per-class virtual id LEADS its help with the unavailability statement on runtimes lacking the class while modern runtimes generate it unchanged. All expectations are derived from the running interpreter, green on 8.6/8.7/9.0 through runtests.tcl on each - native Tcl 8.6 has been a supported runner interpreter since 2026-07-21)
+- `punk/args/` — punk::args tests (`testsuites/args/`): parsing, choices/choicegroups, forms (incl the 2026-08-05 candidacy fencing/fall-through primitive pins ahead of G-168: -regexprefail on optional value slots is form-fatal with no re-landing, unknown-option/dangling-option/option-value-fence failures fall through to sibling forms as successful parses, and the documented per-word limit - a complete option+value+file line double-matches a fenced scriptfile form and a dash-tolerant stdin form), registered-namespace lazy definition loading (`docpackages.test`, G-169 pre-work: inert registration/scan-vs-load split, id_exists never triggers loading, real_id/usage lazy resolution incl tag-prefixed script-level id families, duplicate-definer last-loaded-wins characterization), the G-168 launch-definition model parity (`punkexemodel.test`, punkexe moduledoc 0.7.0, id loading updated for the G-169 handover - the script id resolves via app-punkscript-docs from src/lib (auto_path derived from the test file location) while the moduledoc carries the core-owned ids: script/tclsh selection matrices against the real (script)::punkexe ids with the real-side dispatch/app oracle recorded in goals/archive/G-168, the bare-'-e' viable-incomplete verdict, the ./-e fence message, -encoding fall-through statuses, and the sanctioned complete-'-encoding' multipleformmatches LIMIT pins; the formcheck.test punkexe GAPs flipped to discriminated/sanctioned/selection-sound pins in the same arc), the G-151 landing report (`parsereport.test`, punk::args 0.18.0 parse_report: the canonical flag-like-word-consumed-as-VALUE attribution row, parsed-result vs words+withid entry parity, machine dict shape with declaration-section row order and absent-optional row omission, received xN multiplicity for solos/-multiple opts, type-aware always-marked elision at the default width plus the caller > @cmd -reportvaluewidth > built-in width cascade and never-elided dict returns, VIEW-style single-line-ization of control-bearing values, aliased-optionset storage-key row bridging, bordered-table/tableobject renders, words-form failure errorcode parity with parse, and the registered two-form definition's own render), rendering/indentation characterization, synopsis display characterization (`synopsis.test`: basic italic argname/`<type>` styling, longopt `--x=` alias forms, literal/literalprefix/stringstartswith/stringendswith type-alternates rendering unitalicised, option alternate parenthesization, multi-element clause display incl `?type?` members and argname tail-word hints, `-typesynopsis` value-element lists and option passthrough incl documenter ANSI, and the small-restricted-choice-set literal rule: 1-3 restricted choices render as unitalicised `|`-joined literals in leader/option/value positions with choicegroups counted, >3 or `-choicerestricted 0` falling back to italics, `-typesynopsis` taking precedence), usage-marking characterization (`usagemarking.test`: -parsedargs/-badarg/-parsestatus/-scheme marking primitives plus goodchoice highlighting of selected/default-in-effect choice words, asserted by SGR-parameter subset against the live colour arrays; the G-049 nocolour/colour-leak GAP pins flipped 2026-07-10 to scheme-statelessness assertions), the G-049 parse-status structure (`parsestatus.test`: punk::args::parse_status overall/per-argument statuses, badarg for type/allocation failures, -caller attribution, errorcode -argspecs stripping), -parsekey characterization (`parsekey.test`: result/received/solos/multis keying, shared-key required satisfaction and defaults, mash-path and prefix-abbreviation keying, plus GAP pins for last-defined-member default precedence, cross-member -multiple value loss, and values/leaders parsekey breakage - desired-behaviour pins disabled behind punkargsKnownBug in `testsuites/dev/parsekey-knownbugs.test`; the parsekey/optname collision GAP is flipped (G-083, 2026-08-07: -parsekey colliding with a distinct defined arg's name is now a resolve error unless that arg shares the parsekey), and the G-083 argument-relations define-time vocabulary is pinned in `relations.test` (per-arg -conflicts target validation, @opts -parsekeymode override|error storage and the requires-group/bad-value resolve errors)), longopt style-distinction and mash-edge characterisation (`longopts.test`, 2026-08-07 gap-fill: the gnu (`--flag=` inline-only; spaced/solo usage = badoptionformat) vs plain (`--flag` spaced-only; inline `=` = invalidoption) vs mixed (`-f|--file|--file=` both forms incl longopt prefix abbreviation) definition-grammar distinctions, first-`=`-only value splitting and empty inline values, the two `=`-member resolve-time definition errors, single-dash `-flag=value` never split at the `=`, and `@opts -any 1` adhoc passthrough where `--flag=value` splits but `-flag=value` stays a whole adhoc flagname expecting a value; the same gap-fill added to `mashopts.test`: unknown-letter-in-mash invalidoption rejection and the `-any` interplay - defined flags still mash while undefined mash-lookalike tokens are adhoc flags, never mash attempts; error-shape pins use the first three -errorcode elements), and tclcore doc/interpreter behavioural parity (`tclcoreparity.test`, G-054, gated on have_tclcoredocs: 'string is' class choices equal the live-harvested set, per-class docids exist, error-vs-ok agreement across the probe matrix; version-note labels appear when the class is live OR is a declared forward unavailable class - dict labels on every runtime since G-073, unicode keeps the live-only rule; the G-073 forward-class adoption invariants and the USER-SANCTIONED 'di' prefix-strictness exemption (the model is deliberately stricter than real 8.6, full words parity-true); and the G-166 pin that an unavailable class's per-class virtual id LEADS its help with the unavailability statement on runtimes lacking the class while modern runtimes generate it unchanged. All expectations are derived from the running interpreter, green on 8.6/8.7/9.0 through runtests.tcl on each - native Tcl 8.6 has been a supported runner interpreter since 2026-07-21)
 - `punk/nav/ns/` — punk::nav::ns tests (`testsuites/nav/navns.test`): the n/ n// n/// navigation state machine (ns/ transitions absolute/relative/glob-no-nav, failed-nav state preservation, quad-colon normalization, v-form content selection, ensemble annotation) and the ::punk::nav::ns::ns_current variable contract the repl/codethread/subshell seeding all consume; display content is covered in punk/ns nslist.test
 - `punk/repl/` — punk::repl tests (`testsuites/repl/`): opunk console backend integration (`consolebackends.test`) and repl current-namespace retention (`nscurrent.test`: real codethread via repl::init driven by synchronous runscript sends - inscope evaluation of ns_current, retention across submissions, n/-navigation retained, auto-create-with-notice for missing namespaces, the 2026-07-14 stray-namespace seeding fix pinned behaviourally plus a source-text guard on repl::start's inline template; the end-to-end piped subshell session is covered at shell level by shell/testsuites/punkexe/shellnavns.test - which found the first-subshell shared-code-interp asymmetry and the piped-inscope gap recorded there)
 - `punk/ns/` — punk::ns tests (`testsuites/ns/`): cmdwhich/cmdinfo/cmd_traverse doc-lookup flow (`cmdflow.test`, G-040 parity; plus the G-166 availability axis on the flowunavail/flowunavail_nodoc fixtures - the `unavailable` cmdinfo key present on every result, exact and unique-prefix landings on a `-choiceunavailable` name resolving that name's virtual docid ATTRIBUTED rather than resolving nothing, the choice traverse attributing without addressing when no virtual docid exists, and cmdtype staying unchanged throughout since availability is a second axis, never a cmdtype value), n/ display machinery characterization (`nslist.test`: tier A get_ns_dicts classification buckets as the machine contract for display reworks - incl package tail/prefix derivation, alias edge cases, usageinfo scan-dependence; tier B per-element layout-agnostic marking - underline/underdouble/underdotted namespace package styles, command type tag colours, exported/imported markers, the punkargs doc icon; tier C REWORK-flagged pins of the current hardcoded 2-col/4-col layout and nspath subtables, to flip deliberately with the planned punk-tables/width-responsive rework; plus the flipped nslist_types_default pin - bare nslist without -types displays all member types since punk::ns 0.7.1 fixed the braced-literal -types default), corp proc-retrieval and syntax/untabify interplay (`corp.test`: name edge cases, -ranges/-n line handling, basic-highlight ansistrip equivalence, -untabify spaces/unicode tab-free output, the KNOWN-DEFICIENCY pin for default -untabify none on tabbed bodies - grepstr warns per pass and brace overlays mangle tabbed lines, deterministic under mocked console tabstops - and a ::tcl::CopyDirectory -untabify spaces smoke test; precursor coverage for the planned punk::ns hygiene pass), cmdtrace characterization (`cmdtrace.test`: -pause 0 non-interactive runs, linedict line-mark keys for flat and 2-word-form nested switches as correct-mark guards, and GAP pins for the upstream nested-switch mismark - core.tcl-lang.org tktview 5d5b1052280c976ea3d4, arm bodies whose split-list index lands on a literal switch-command word report container-relative lines; mark tests gated on have_tclcoredocs because cmdtrace's arm-offset correction parses against the ::switch argdoc; plus the fixed-canary asserting punk::lib::check::has_tclbug_nestedswitch_tracelines still reports the bug - a live behavioural probe, so a fixed Tcl release fails the canary first and triggers the documented flip workflow), cmdhelp usage-rendering integration (`cmdhelp.test`: scheme selection, goodarg/badarg marking incl type/allocation failures, goodchoice highlighting of supplied/default choice words, alias path, cmdinfo result shape, queried-command failure attribution, and `-return dict` parse-status returns (G-049 - its GAP pins flipped 2026-07-10); the flipped G-051 pins for pseudo-command cmdtype (`doconly`) + space-form docid prefixes (real `string is` pins behind the have_tclcoredocs constraint); the G-166 unavailability marking on the helpstrua fixture and on the real `string is dict` subject - the `-return dict` key, the table/string marking with the info scheme suppressed so a valid argument tail no longer renders as a cleanly usable command line, and the `-return text` leading `UNAVAILABLE:` line (the two deliberate key-list flips - `cmdhelp_cmdinfo_result_shape`, `cmdhelp_return_dict_valid` - landed with it); remaining GAP pins for TclOO undocumented-method fallback (G-052) and synopsis marking absence (G-050); plus the G-150 flag-led form-narrowing + selection-soundness pins against punk::auto_exec::hash - bare-parse selection contract (incl the dash-led-name noformmatch cost), no-word/unknown-flag/ambiguity whole-render fallbacks, and hash runtime-behaviour-unchanged), and name/path primitive characterization (`nsprimitives.test`: string pins for nsparts/nsprefix/nstail/nsjoin/nsjoinall incl weird colon-run (`:::`) splitting, the trailing-colon parse ambiguity (`::x:` + `y` joins to the same string as `::x` + `:y` and reparses leading-colon-greedy), and prefix/tail/join round-trip and its absolutizing exceptions (the original twin-divergence pins for nsparts1/nsprefix1/nsprefix_orig/nstail1/nstail_orig served as safe-deletion evidence and were removed with the twins in the punk::ns 0.7.0 hygiene pass - divergence record in this file's git history, commit 0c7168a1); plus nseval fq-requirement/create-on-eval/evaluator-proc caching, the native-vs-punk `p:::x` resolution divergence (native namespace eval reaches child `x`, nseval creates/reaches literal `:x`), nseval_ifexists no-create + error propagation on plain and genuinely weird namespaces, nsexists/nschildren/nstree_raw weird-ns and relative-resolution pins, globmatchns `*`/`**`/`?` semantics (incl `*` matching a single inner colon - a formerly stale 'should be fixed' comment above nsglob_as_re was corrected in the 0.7.0 hygiene pass), and nspath_to_absolute/nspath_here_absolute caller-resolution pins; the nsjoinall error-message wart pin ('nsjoin:' prefix) flipped when punk::ns 0.7.1 fixed it)
diff --git a/src/tests/modules/punk/args/testsuites/args/parsekey.test b/src/tests/modules/punk/args/testsuites/args/parsekey.test
index 02b7ef49..843b11e0 100644
--- a/src/tests/modules/punk/args/testsuites/args/parsekey.test
+++ b/src/tests/modules/punk/args/testsuites/args/parsekey.test
@@ -358,24 +358,29 @@ namespace eval ::testspace {
         ]
 
 
-    #added 2026-07-14 (agent) - parsekey coverage review.
-    #GAP: no define-time validation when a -parsekey value collides with another defined
-    #option's name. The two options silently conflate into an implicit shared-key group
-    #(last received wins under the common key).
-    test parsekey_collides_with_defined_optname_GAP {GAP: -parsekey matching another option's name silently forms an implicit group}\
+    #added 2026-07-14 (agent) - parsekey coverage review; flipped 2026-08-07 (G-083).
+    #A -parsekey value colliding with a distinct defined option's name used to silently
+    #form an implicit shared-key group (last received wins). It is now a define-time error:
+    #resolve rejects it unless the named option also declares the same -parsekey.
+    test parsekey_collides_with_defined_optname {-parsekey matching another option's name is a define-time error unless that option shares the parsekey}\
         -setup $common -body {
             set docids [list]
 
-            set argd [punk::args::parse {-a 1 -b 2} withdef @opts {-a -parsekey -b -type string} {-b -type string}]
-            lappend docids [dict get $argd id]
-            lappend result [dict get $argd opts]
-            lappend result [dict get $argd received]
+            #colliding parsekey - resolve rejects at parse (definitions are lazy)
+            try {
+                punk::args::parse {-a 1 -b 2} withdef @opts {-a -parsekey -b -type string} {-b -type string}
+                lappend result "UNEXPECTED-accepted-collision"
+            } on error {emsg eopts} {
+                lappend result [string match "*collides with the name of defined argument*" $emsg]
+            }
 
-            set argd [punk::args::parse {-a 1} withdef @opts {-a -parsekey -b -type string} {-b -type string}]
+            #an option naming its OWN parsekey is not a collision - -b -parsekey -b is redundant but legal
+            set argd [punk::args::parse {-b 2} withdef @opts {-b -parsekey -b -type string}]
             lappend docids [dict get $argd id]
             lappend result [dict get $argd opts]
 
-            set argd [punk::args::parse {-b 2} withdef @opts {-a -parsekey -b -type string} {-b -type string}]
+            #a deliberate shared-key group where one member's name matches the parsekey is legal
+            set argd [punk::args::parse {-a 1} withdef @opts {-a -parsekey -b -type string} {-b -parsekey -b -type string}]
             lappend docids [dict get $argd id]
             lappend result [dict get $argd opts]
         }\
@@ -385,10 +390,9 @@ namespace eval ::testspace {
             }
         }\
         -result [list\
+            1\
             {-b 2}\
-            {-b 0 -b 1}\
             {-b 1}\
-            {-b 2}
         ]
 
 
diff --git a/src/tests/modules/punk/args/testsuites/args/relations.test b/src/tests/modules/punk/args/testsuites/args/relations.test
new file mode 100644
index 00000000..08b91454
--- /dev/null
+++ b/src/tests/modules/punk/args/testsuites/args/relations.test
@@ -0,0 +1,116 @@
+package require tcltest
+package require punk::args
+
+#G-083 argument relations: -conflicts (per-arg) and -parsekeymode (per @opts group).
+#This file pins the DEFINE-TIME vocabulary (spec-compiler storage and validation);
+#the parse-time optionconflict enforcement is pinned in validation.test and
+#parsekey.test. Error-shape pins use the first three -errorcode elements where the
+#failure surfaces through parse, and distinctive message substrings for resolve-time
+#definition errors (plain text, no ANSI) - the longopts.test/mashopts.test convention.
+#Definitions are lazy: resolve errors surface at first parse, so the parse path is
+#used to trigger them and the message substring is pinned.
+
+namespace eval ::testspace {
+    namespace import ::tcltest::*
+    variable common {
+        set result ""
+    }
+
+    #added 2026-08-07 (agent) - G-083 define-time vocabulary characterisation
+    test parsekeymode_requires_group {@opts -parsekeymode without -group is a resolve error}\
+        -setup $common -body {
+            try {
+                punk::args::parse {} withdef {@opts -parsekeymode error} {-x -type none}
+                lappend result "UNEXPECTED-accepted"
+            } on error {emsg eopts} {
+                lappend result [string match "*-parsekeymode requires -group*" $emsg]
+            }
+            set result
+        }\
+        -result [list 1]
+
+    test parsekeymode_bad_value {@opts -parsekeymode with a value other than override|error is a resolve error}\
+        -setup $common -body {
+            try {
+                punk::args::parse {} withdef {@opts -group G -parsekeymode strict} {-x -type none}
+                lappend result "UNEXPECTED-accepted"
+            } on error {emsg eopts} {
+                lappend result [string match "*-parsekeymode must be 'override' or 'error'*" $emsg]
+            }
+            set result
+        }\
+        -result [list 1]
+
+    test parsekeymode_stored {@opts -parsekeymode error with -group is accepted and stored on the OPT_GROUPS entry}\
+        -setup $common -body {
+            set argd [punk::args::parse {} withdef {@opts -group G -parsekeymode error} {-x -type none}]
+            lappend docids [dict get $argd id]
+            set spec [punk::args::get_spec [dict get $argd id]]
+            dict for {fid fd} [dict get $spec FORMS] {
+                if {[dict exists $fd OPT_GROUPS G -parsekeymode]} {
+                    lappend result [dict get $fd OPT_GROUPS G -parsekeymode]
+                }
+            }
+            set result
+        }\
+        -cleanup {
+            foreach id $docids {punk::args::undefine $id 1}
+        }\
+        -result [list error]
+
+    test parsekeymode_default_override {an @opts group without -parsekeymode stores the default override}\
+        -setup $common -body {
+            set argd [punk::args::parse {} withdef {@opts -group G} {-x -type none}]
+            lappend docids [dict get $argd id]
+            set spec [punk::args::get_spec [dict get $argd id]]
+            dict for {fid fd} [dict get $spec FORMS] {
+                if {[dict exists $fd OPT_GROUPS G -parsekeymode]} {
+                    lappend result [dict get $fd OPT_GROUPS G -parsekeymode]
+                }
+            }
+            set result
+        }\
+        -cleanup {
+            foreach id $docids {punk::args::undefine $id 1}
+        }\
+        -result [list override]
+
+    test conflicts_unknown_target {per-arg -conflicts naming an unknown flag/parsekey is a resolve error}\
+        -setup $common -body {
+            try {
+                punk::args::parse {} withdef @opts {-x -type none -conflicts -nope}
+                lappend result "UNEXPECTED-accepted"
+            } on error {emsg eopts} {
+                lappend result [string match "*-conflicts for argument '-x' names '-nope' which is neither a defined argument name nor a declared -parsekey*" $emsg]
+            }
+            set result
+        }\
+        -result [list 1]
+
+    test conflicts_valid_flagname_target {per-arg -conflicts naming a defined flag is accepted at define time}\
+        -setup $common -body {
+            #accepted at define time (parse-time enforcement lands in a later G-083 increment)
+            set argd [punk::args::parse {-x -y} withdef @opts {-x -type none -conflicts -y} {-y -type none}]
+            lappend docids [dict get $argd id]
+            lappend result ok
+            set result
+        }\
+        -cleanup {
+            foreach id $docids {punk::args::undefine $id 1}
+        }\
+        -result [list ok]
+
+    test conflicts_valid_parsekey_target {per-arg -conflicts naming a declared -parsekey is accepted at define time}\
+        -setup $common -body {
+            set argd [punk::args::parse {-x -y} withdef @opts {-x -type none -parsekey -pk -conflicts -y} {-y -type none -parsekey -pk}]
+            lappend docids [dict get $argd id]
+            lappend result ok
+            set result
+        }\
+        -cleanup {
+            foreach id $docids {punk::args::undefine $id 1}
+        }\
+        -result [list ok]
+
+}
+tcltest::cleanupTests ;#needed to produce test summary line.
\ No newline at end of file