punkshell/goals/G-093-runtests-includepaths-discovery.md

G-093 runtests -include-paths multi-pattern/repeated-flag discovery: investigate and fix

Status: proposed Scope: src/tests/runtests.tcl, src/modules/punk/path-999999.0a1.0.tm (treefilenames/globmatchpath as implicated), src/modules/punk/args-999999.0a1.0.tm (only if -multiple implicated), src/tests/ (runner-targeting regression suite), src/tests/AGENTS.md Goal: runtests.tcl -include-paths discovery honours its documented contract - a single value carrying multiple space-separated glob patterns includes every pattern's matches, repeated -include-paths flags accumulate, and deep ** patterns match regardless of whether explicit file-tail globs are supplied - with the verified semantics pinned by a regression suite and the root cause recorded. Acceptance: the two 2026-07-19 failures reproduce as characterization tests before the fix and pass after it - (a) a single -include-paths value listing four deep patterns (the G-092 measurement set) discovers files from all four subtrees under the default *.test tail glob, and (b) two repeated -include-paths flags naming distinct subtrees discover both (observed matching zero files); the root cause is identified and recorded in this file; a regression suite under src/tests covers single-value multi-pattern, repeated-flag, deep-pattern and tail-glob-present/absent combinations; a full-suite default-discovery run before and after the fix compares PARITY ok via scriptlib/developer/runtests_parity.tcl (default '**' discovery must be unaffected); src/tests/AGENTS.md -include-paths wording is reconciled with the verified semantics.

Context

Observed 2026-07-19 during the G-092 child-wall measurements (also recorded in goals/archive/G-092-split-longrunning-testfiles.md):

• FAILED (one of four matched): a single value with four deep patterns and no tail globs - -include-paths 'modules/punk/mix/testsuites/scriptwrap/** shell/testsuites/binscripts/** modules/argparsingtest/** shell/testsuites/punkexe/**' - discovered only the modules/argparsingtest file (1 file instead of ~10).
• FAILED (zero matched): the same subtrees supplied as repeated -include-paths flags, no tail globs - discovered 0 files, despite src/tests/AGENTS.md documenting accumulate semantics for repeated flags ("-multiple 1 as of 2026-07-10; previously the last flag silently won").
• WORKED in the same session: a multi-pattern single value WITH explicit file-tail globs (three patterns + six tails matched files across three subtrees); a single deep pattern with no tails ('modules/punk/args/' matched 28 files); the default ''.
• WORKED standalone: punk::path::globmatchpath matched the same deep patterns against full relative paths in isolation (e.g shell/testsuites/stdin/** vs shell/testsuites/stdin/runstdin.test -> 1), pointing suspicion at the treefilenames walk/prune path or the option-value shape handed to it rather than the matcher itself.
• Failure correlation so far: multi-pattern or repeated-flag forms combined with the DEFAULT tail glob; the same include-path forms with explicit tails worked. Not yet minimized - the first investigation step is a reduction against a small fixture tree.
• Workaround in use since: file-tail glob targeting (multiple tails are independent matches - documented in src/tests/AGENTS.md Work Guidance).

Candidate root causes to check (from the runtests side inward):

• runtests.tcl flattens the -multiple option value with 'concat {*}' - verify the shape it hands treefilenames for each invocation form (one list value vs list-of-occurrence-lists).
• punk::path::treefilenames' recursive walk/prune: whether directory descent decisions consult every include pattern or effectively only one when tail globs are defaulted.
• punk::args -multiple accumulation for -type list options (only if the received value shape contradicts its documentation).

Notes

• treefilenames already implements -exclude-paths (argdoc documents tailbase-relative matching) but runtests does not expose it. A runtests -exclude-paths option (discussed 2026-07-19 as a middle ground between full and targeted runs) would ride the same discovery machinery - implement or verify it alongside this fix so both directions' multi-pattern semantics get pinned by the same regression suite, or filter post-discovery over the returned relative paths via globmatchpath (shown reliable standalone).