cleaner src/tests/runtests.tcl output for agents based on new -report option etc

src/tests/AGENTS.md

@@ -17,6 +17,8 @@ Top-level test harness and source-tree tests for ShellSpy/Punk. Tests here exerc
 - `runtests.tcl` excludes `AGENTS.md` and `*.tcl` helper files when discovering `.test` files.
 - Tests should run against source modules and libraries from `src/`, not installed packages or root-level build outputs.
 - Test files must `package require` any extra packages explicitly.
+- Agent-oriented runner output should use `-report compact -show-passes 0` for focused checks unless detailed Markdown pass lists are needed.
+- `-report json` emits a machine-readable final summary, but package-load warnings may still precede it on stdout/stderr.
 
 ## Work Guidance
 
@@ -24,12 +26,15 @@ Top-level test harness and source-tree tests for ShellSpy/Punk. Tests here exerc
 - 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 `-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>`.
+- Add `-slowest <n>` when timing outliers are relevant.
+- Add `-strict-exit 1` when a nonzero shell exit code is needed for failures or parser warnings.
 - Capture enough stderr or failure context to identify the failing command or assertion.
 
 ## Verification
 
 - `<tcl_interpreter> src/tests/runtests.tcl` passes when broad source-tree test coverage is relevant.
-- Focused checks use `<tcl_interpreter> src/tests/runtests.tcl -include-paths <relative/path/**>` and optional file-tail globs.
+- Focused checks use `<tcl_interpreter> src/tests/runtests.tcl -report compact -show-passes 0 -include-paths <relative/path/**>` and optional file-tail globs.
 - Documentation-only changes are verified by reviewing the affected DOX chain and diff.
 
 ## Child DOX Index

src/tests/core/AGENTS.md

@@ -1,31 +1,31 @@
-# src/tests/core — Tcl Core Compatibility Tests
-
-## Purpose
-
-Selected tests taken from or modeled after Tcl core tests. These tests should produce compatible results under a standard `tclsh` and an appropriate built Punk executable.
-
-## Ownership
-
-- Agents may update this subtree when changing compatibility expectations or test harness behavior for core Tcl commands.
-- Preserve the intent of upstream Tcl compatibility coverage when editing imported or adapted tests.
-
-## Local Contracts
-
-- Tests under this subtree are compatibility tests, not general module behavior tests.
-- Keep command behavior expectations explicit enough to compare standard Tcl and built Punk results.
-- Avoid mixing source-module feature tests into this subtree; use `src/tests/modules/` instead.
-
-## Work Guidance
-
-- Use `src/tests/runtests.tcl` from the repository root for source-tree harness runs.
-- Prefer focused `-include-paths core/**` checks when editing only this subtree.
-- Document any deliberate divergence from standard Tcl behavior in the nearest relevant test file or child AGENTS.md.
-
-## Verification
-
-- `<tcl_interpreter> src/tests/runtests.tcl -include-paths core/**` passes for changes in this subtree.
-- Compare results with standard `tclsh` and the target Punk executable when compatibility behavior is the subject of the change.
-
-## Child DOX Index
-
-- `tcl/testsuites/tests/` — Imported/adapted Tcl core test files (see tcl/testsuites/tests/AGENTS.md)
+# src/tests/core — Tcl Core Compatibility Tests
+
+## Purpose
+
+Selected tests taken from or modeled after Tcl core tests. These tests should produce compatible results under a standard `tclsh` and an appropriate built Punk executable.
+
+## Ownership
+
+- Agents may update this subtree when changing compatibility expectations or test harness behavior for core Tcl commands.
+- Preserve the intent of upstream Tcl compatibility coverage when editing imported or adapted tests.
+
+## Local Contracts
+
+- Tests under this subtree are compatibility tests, not general module behavior tests.
+- Keep command behavior expectations explicit enough to compare standard Tcl and built Punk results.
+- Avoid mixing source-module feature tests into this subtree; use `src/tests/modules/` instead.
+
+## Work Guidance
+
+- Use `src/tests/runtests.tcl` from the repository root for source-tree harness runs.
+- Prefer focused `-report compact -show-passes 0 -include-paths core/**` checks when editing only this subtree.
+- Document any deliberate divergence from standard Tcl behavior in the nearest relevant test file or child AGENTS.md.
+
+## Verification
+
+- `<tcl_interpreter> src/tests/runtests.tcl -report compact -show-passes 0 -include-paths core/**` passes for changes in this subtree.
+- Compare results with standard `tclsh` and the target Punk executable when compatibility behavior is the subject of the change.
+
+## Child DOX Index
+
+- `tcl/testsuites/tests/` — Imported/adapted Tcl core test files (see tcl/testsuites/tests/AGENTS.md)

src/tests/core/tcl/testsuites/tests/AGENTS.md

@@ -1,27 +1,27 @@
-# src/tests/core/tcl/testsuites/tests — Tcl Core Test Files
-
-## Purpose
-
-A selection of unit tests taken from or modeled after the Tcl core distribution. These tests, designed for a standard `tclsh`, should produce the same results for a suitable built Punk executable.
-
-## Ownership
-
-- Preserve Tcl core compatibility intent when editing tests in this directory.
-- Keep broader core-test rules in `src/tests/core/AGENTS.md`.
-
-## Local Contracts
-
-- Tests here target Tcl command compatibility, not general Punk module behavior.
-- Deliberate Punk divergences from standard Tcl behavior must be documented near the affected test.
-
-## Work Guidance
-
-- Use focused runs through `src/tests/runtests.tcl` with `-include-paths core/tcl/testsuites/tests/**`.
-
-## Verification
-
-- `<tcl_interpreter> src/tests/runtests.tcl -include-paths core/tcl/testsuites/tests/**` passes for changes in this directory.
-
-## Child DOX Index
-
-
+# src/tests/core/tcl/testsuites/tests — Tcl Core Test Files
+
+## Purpose
+
+A selection of unit tests taken from or modeled after the Tcl core distribution. These tests, designed for a standard `tclsh`, should produce the same results for a suitable built Punk executable.
+
+## Ownership
+
+- Preserve Tcl core compatibility intent when editing tests in this directory.
+- Keep broader core-test rules in `src/tests/core/AGENTS.md`.
+
+## Local Contracts
+
+- Tests here target Tcl command compatibility, not general Punk module behavior.
+- Deliberate Punk divergences from standard Tcl behavior must be documented near the affected test.
+
+## Work Guidance
+
+- Use focused runs through `src/tests/runtests.tcl` with `-report compact -show-passes 0 -include-paths core/tcl/testsuites/tests/**`.
+
+## Verification
+
+- `<tcl_interpreter> src/tests/runtests.tcl -report compact -show-passes 0 -include-paths core/tcl/testsuites/tests/**` passes for changes in this directory.
+
+## Child DOX Index
+
+

src/tests/modules/AGENTS.md

@@ -1,34 +1,36 @@
-# src/tests/modules — Source Module Test Suites
-
-## Purpose
-
-Unit tests for editable source modules under `src/modules/`, `src/modules_tcl8/`, and `src/modules_tcl9/`. These tests use `tcltest` and run against the uninstalled source tree through `src/tests/runtests.tcl`.
-
-## Ownership
-
-- Agents should add or update tests here when changing module behavior in `src/modules/` or Tcl-version-specific module trees.
-- Installed-module test packages under `src/modules/test/` are packaging artifacts and are not the default place for source-tree behavior tests.
-- Do not delete, skip, or weaken existing tests without explicit user direction.
-
-## Local Contracts
-
-- The directory hierarchy mirrors module namespace paths, such as `src/tests/modules/punk/args/` for `punk::args`.
-- Test files use `.test` extension and must `package require` any extra packages explicitly.
-- Test files may commonly use line-continuation backslashes, and existing Tcl expand-syntax structures in tests should not be refactored into line continuations.
-- Tests must exercise source modules as loaded by `src/tests/runtests.tcl`, not installed or built output modules.
-
-## Work Guidance
-
-- Put new module tests under `src/tests/modules/<namespacepath>/testsuites/<suite>/` following nearby layout.
-- Prefer `try { ... } on error {result options} { ... }` for structured error capture in test bodies.
-- Focused verification should mirror production pipelines inside tests using Punk pipeline syntax when that parity matters.
-- Capture enough stderr or failure context to identify the failing command or assertion.
-
-## Verification
-
-- Run targeted module tests with `<tcl_interpreter> src/tests/runtests.tcl -include-paths modules/<namespacepath>/**`.
-- Run a single test by name with `<tcl_interpreter> src/tests/runtests.tcl -tcltestoptions {-match <test_name>} -include-paths modules/<namespacepath>/**`.
-- Run a specific test file by adding its file tail, such as `<tcl_interpreter> src/tests/runtests.tcl -include-paths modules/punk/args/** parsekey.test`.
-
-## Child DOX Index
-
+# src/tests/modules — Source Module Test Suites
+
+## Purpose
+
+Unit tests for editable source modules under `src/modules/`, `src/modules_tcl8/`, and `src/modules_tcl9/`. These tests use `tcltest` and run against the uninstalled source tree through `src/tests/runtests.tcl`.
+
+## Ownership
+
+- Agents should add or update tests here when changing module behavior in `src/modules/` or Tcl-version-specific module trees.
+- Installed-module test packages under `src/modules/test/` are packaging artifacts and are not the default place for source-tree behavior tests.
+- Do not delete, skip, or weaken existing tests without explicit user direction.
+
+## Local Contracts
+
+- The directory hierarchy mirrors module namespace paths, such as `src/tests/modules/punk/args/` for `punk::args`.
+- Test files use `.test` extension and must `package require` any extra packages explicitly.
+- Test files may commonly use line-continuation backslashes, and existing Tcl expand-syntax structures in tests should not be refactored into line continuations.
+- Tests must exercise source modules as loaded by `src/tests/runtests.tcl`, not installed or built output modules.
+
+## Work Guidance
+
+- Put new module tests under `src/tests/modules/<namespacepath>/testsuites/<suite>/` following nearby layout.
+- For efficient agent runs, use `-report compact -show-passes 0` and include the narrowest namespace path plus file tail when known.
+- Prefer `try { ... } on error {result options} { ... }` for structured error capture in test bodies.
+- Focused verification should mirror production pipelines inside tests using Punk pipeline syntax when that parity matters.
+- Capture enough stderr or failure context to identify the failing command or assertion.
+
+## Verification
+
+- Run targeted module tests with `<tcl_interpreter> src/tests/runtests.tcl -report compact -show-passes 0 -include-paths modules/<namespacepath>/**`.
+- Run a single test by name with `<tcl_interpreter> src/tests/runtests.tcl -report compact -show-passes 0 -tcltestoptions {-match <test_name>} -include-paths modules/<namespacepath>/**`.
+- Run a specific test file by adding its file tail, such as `<tcl_interpreter> src/tests/runtests.tcl -report compact -show-passes 0 -include-paths modules/punk/args/** parsekey.test`.
+- Use `-report markdown+json` when both detailed human-readable failure sections and a structured summary are useful.
+
+## Child DOX Index
+

src/tests/modules/punk/path/testsuites/tests/path.test

@@ -471,9 +471,8 @@ namespace eval ::testspace {
             }
             expr {$results eq {1 1 1}}
         } \
-        -constraints foobar \
         -cleanup $treefilenames_cleanup \
-        -result 1a
+        -result 1
 }
 
 tcltest::cleanupTests ;#needed to produce test summary.

src/tests/shell/AGENTS.md

@@ -1,29 +1,29 @@
-# src/tests/shell — Shell Behavior Tests
-
-## Purpose
-
-Tests for shell-level behavior, command-line execution, and stdin/stdout interaction that are not owned by a specific source module namespace.
-
-## Ownership
-
-- Agents may update this subtree when changing shell behavior, command execution, or interactive stream handling.
-- Keep module API behavior tests in `src/tests/modules/` unless shell invocation is the behavior under test.
-
-## Local Contracts
-
-- Tests here may exercise process execution, stdin, stdout, stderr, and shell filtering behavior.
-- Keep command inputs and expected outputs explicit so failures can be reproduced outside the aggregate runner.
-- Avoid relying on installed packages or root-level build outputs unless the test explicitly targets a built executable.
-
-## Work Guidance
-
-- Use focused harness runs with `-include-paths shell/**` when editing this subtree.
-- Include enough failure output to identify the launched command and stream comparison.
-- Keep platform-sensitive assumptions visible in the test body.
-
-## Verification
-
-- `<tcl_interpreter> src/tests/runtests.tcl -include-paths shell/**` passes for changes in this subtree.
-
-## Child DOX Index
-
+# src/tests/shell — Shell Behavior Tests
+
+## Purpose
+
+Tests for shell-level behavior, command-line execution, and stdin/stdout interaction that are not owned by a specific source module namespace.
+
+## Ownership
+
+- Agents may update this subtree when changing shell behavior, command execution, or interactive stream handling.
+- Keep module API behavior tests in `src/tests/modules/` unless shell invocation is the behavior under test.
+
+## Local Contracts
+
+- Tests here may exercise process execution, stdin, stdout, stderr, and shell filtering behavior.
+- Keep command inputs and expected outputs explicit so failures can be reproduced outside the aggregate runner.
+- Avoid relying on installed packages or root-level build outputs unless the test explicitly targets a built executable.
+
+## Work Guidance
+
+- Use focused harness runs with `-report compact -show-passes 0 -include-paths shell/**` when editing this subtree.
+- Include enough failure output to identify the launched command and stream comparison.
+- Keep platform-sensitive assumptions visible in the test body.
+
+## Verification
+
+- `<tcl_interpreter> src/tests/runtests.tcl -report compact -show-passes 0 -include-paths shell/**` passes for changes in this subtree.
+
+## Child DOX Index
+