runtests.tcl: -include-paths -multiple 1 - repeated flags accumulate (last-wins footgun fixed)

- Repeated -include-paths flags previously overrode each other silently (standard
  non-multiple punk::args opt semantics), quietly narrowing the test selection
  while reporting green - a recurring misuse driven by Unix-CLI accumulate-flag
  muscle memory (gcc -I / curl -H style).
- The option is now -multiple 1: repeated flags accumulate, the single
  space-separated quoted list form is unchanged, and the unreceived default {**}
  passes through (the consumer flattens occurrences with concat). Help text
  documents both forms as equivalent.
- src/tests/AGENTS.md work-guidance updated. Known remaining sibling issue:
  multiple trailing file-tail globs still silently match 0 files.
- Verified: repeated-flag and single-list invocations select identical file sets
  (20 files / 189 tests) on Tcl 9.0.3, repeated-flag accumulation on 8.7, and a
  no-flag default run with a file-tail glob unchanged. The general strict-arity
  mechanism is proposed as G-053.

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

src/tests/AGENTS.md

@@ -32,7 +32,7 @@ Top-level test harness and source-tree tests for ShellSpy/Punk. Tests here exerc
 
 - Select an appropriate interpreter, such as `tclsh`, `tclsh90`, or a built Punk executable such as `punk902z`.
 - Run the full source-tree suite with `<tcl_interpreter> src/tests/runtests.tcl`.
-- Use `-include-paths` with paths relative to `src/tests/`, using forward slashes.
+- Use `-include-paths` with paths relative to `src/tests/`, using forward slashes. The flag accepts a space-separated list of glob patterns and may also be repeated, with all occurrences accumulating (`-multiple 1` as of 2026-07-10; previously the last flag silently won).
 - Use `-tcltestoptions {-match <test_name>}` for focused single-test runs.
 - For agent-efficient focused runs, prefer `<tcl_interpreter> src/tests/runtests.tcl -report compact -show-passes 0 -include-paths <relative/path/**> <file-tail.test>`.
 - Treat `RUNTESTS_RESULT status=warn` and compact warning reasons such as `missing-cleanupTests` as incomplete test results, even if observed pass events are listed.

src/tests/runtests.tcl

@@ -367,13 +367,17 @@ punk::args::define {
               and
               stderr from <testfile>
               "
-        -include-paths -type list -default {**} -help\
+        -include-paths -type list -default {**} -multiple 1 -help\
             "List of glob patterns for paths.
              Paths are relative to the test base and should use forward slashes as separators.
 
              Only test files under paths matching these patterns will be included.
              For example, to only include test files under <projectdir>/src/modules/punk
-              -include-paths {modules/punk/**}"
+              -include-paths {modules/punk/**}
+             The flag may also be repeated, with all occurrences accumulating:
+              -include-paths modules/punk/args/** -include-paths modules/punk/ns/**
+             is equivalent to
+              -include-paths {modules/punk/args/** modules/punk/ns/**}"
         -report -type string -default markdown -choices {markdown compact json markdown+json} -help\
             "Output report style. markdown preserves the detailed human-readable report.
              compact prints a short Markdown report with failures, warnings, and optional slow tests.
@@ -420,7 +424,9 @@ set report_json_only         [expr {$opt_report eq "json"}]
 set report_emit_json         [expr {$opt_report in {json markdown+json}}]
 
 
-set include_paths   [dict get $opts -include-paths]
+#-include-paths is -multiple 1: each occurrence contributes a list of patterns - flatten
+#(the unreceived default {**} and single-occurrence usage flatten to themselves)
+set include_paths   [concat {*}[dict get $opts -include-paths]]
 
 
 set tcltestoptions [dict merge $default_tcltestoptions $opt_tcltestoptions]