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
+# src/tests/core — Tcl Core Compatibility Tests
-
+
-## Purpose
+## 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.
+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
+## Ownership
-
+
-- Agents may update this subtree when changing compatibility expectations or test harness behavior for core Tcl commands.
+- 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.
+- Preserve the intent of upstream Tcl compatibility coverage when editing imported or adapted tests.
-
+
-## Local Contracts
+## Local Contracts
-
+
-- Tests under this subtree are compatibility tests, not general module behavior tests.
+- 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.
+- 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.
+- Avoid mixing source-module feature tests into this subtree; use `src/tests/modules/` instead.
-
+
-## Work Guidance
+## Work Guidance
-
+
-- Use `src/tests/runtests.tcl` from the repository root for source-tree harness runs.
+- 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.
+- 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.
+- Document any deliberate divergence from standard Tcl behavior in the nearest relevant test file or child AGENTS.md.
-
+
-## Verification
+## Verification
-
+
-- `<tcl_interpreter> src/tests/runtests.tcl -include-paths core/**` passes for changes in this subtree.
+- `<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.
+- Compare results with standard `tclsh` and the target Punk executable when compatibility behavior is the subject of the change.
-
+
-## Child DOX Index
+## Child DOX Index
-
+
-- `tcl/testsuites/tests/` — Imported/adapted Tcl core test files (see tcl/testsuites/tests/AGENTS.md)
+- `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
+# src/tests/core/tcl/testsuites/tests — Tcl Core Test Files
-
+
-## Purpose
+## 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.
+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
+## Ownership
-
+
-- Preserve Tcl core compatibility intent when editing tests in this directory.
+- Preserve Tcl core compatibility intent when editing tests in this directory.
-- Keep broader core-test rules in `src/tests/core/AGENTS.md`.
+- Keep broader core-test rules in `src/tests/core/AGENTS.md`.
-
+
-## Local Contracts
+## Local Contracts
-
+
-- Tests here target Tcl command compatibility, not general Punk module behavior.
+- 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.
+- Deliberate Punk divergences from standard Tcl behavior must be documented near the affected test.
-
+
-## Work Guidance
+## Work Guidance
-
+
-- Use focused runs through `src/tests/runtests.tcl` with `-include-paths core/tcl/testsuites/tests/**`.
+- Use focused runs through `src/tests/runtests.tcl` with `-report compact -show-passes 0 -include-paths core/tcl/testsuites/tests/**`.
-
+
-## Verification
+## Verification
-
+
-- `<tcl_interpreter> src/tests/runtests.tcl -include-paths core/tcl/testsuites/tests/**` passes for changes in this directory.
+- `<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
+## Child DOX Index
-
+
-
+

src/tests/modules/AGENTS.md

@@ -1,34 +1,36 @@
-# src/tests/modules — Source Module Test Suites
+# src/tests/modules — Source Module Test Suites
-
+
-## Purpose
+## 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`.
+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
+## Ownership
-
+
-- Agents should add or update tests here when changing module behavior in `src/modules/` or Tcl-version-specific module trees.
+- 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.
+- 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.
+- Do not delete, skip, or weaken existing tests without explicit user direction.
-
+
-## Local Contracts
+## Local Contracts
-
+
-- The directory hierarchy mirrors module namespace paths, such as `src/tests/modules/punk/args/` for `punk::args`.
+- 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 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.
+- 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.
+- Tests must exercise source modules as loaded by `src/tests/runtests.tcl`, not installed or built output modules.
-
+
-## Work Guidance
+## Work Guidance
-
+
-- Put new module tests under `src/tests/modules/<namespacepath>/testsuites/<suite>/` following nearby layout.
+- 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.
+- For efficient agent runs, use `-report compact -show-passes 0` and include the narrowest namespace path plus file tail when known.
-- Focused verification should mirror production pipelines inside tests using Punk pipeline syntax when that parity matters.
+- Prefer `try { ... } on error {result options} { ... }` for structured error capture in test bodies.
-- Capture enough stderr or failure context to identify the failing command or assertion.
+- 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
+
-
+## 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 targeted module tests with `<tcl_interpreter> src/tests/runtests.tcl -report compact -show-passes 0 -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`.
+- 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`.
-## Child DOX Index
+- 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
+# src/tests/shell — Shell Behavior Tests
-
+
-## Purpose
+## Purpose
-
+
-Tests for shell-level behavior, command-line execution, and stdin/stdout interaction that are not owned by a specific source module namespace.
+Tests for shell-level behavior, command-line execution, and stdin/stdout interaction that are not owned by a specific source module namespace.
-
+
-## Ownership
+## Ownership
-
+
-- Agents may update this subtree when changing shell behavior, command execution, or interactive stream handling.
+- 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.
+- Keep module API behavior tests in `src/tests/modules/` unless shell invocation is the behavior under test.
-
+
-## Local Contracts
+## Local Contracts
-
+
-- Tests here may exercise process execution, stdin, stdout, stderr, and shell filtering behavior.
+- 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.
+- 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.
+- Avoid relying on installed packages or root-level build outputs unless the test explicitly targets a built executable.
-
+
-## Work Guidance
+## Work Guidance
-
+
-- Use focused harness runs with `-include-paths shell/**` when editing this subtree.
+- 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.
+- Include enough failure output to identify the launched command and stream comparison.
-- Keep platform-sensitive assumptions visible in the test body.
+- Keep platform-sensitive assumptions visible in the test body.
-
+
-## Verification
+## Verification
-
+
-- `<tcl_interpreter> src/tests/runtests.tcl -include-paths shell/**` passes for changes in this subtree.
+- `<tcl_interpreter> src/tests/runtests.tcl -report compact -show-passes 0 -include-paths shell/**` passes for changes in this subtree.
-
+
-## Child DOX Index
+## Child DOX Index
-
+