Update specification of policies for cmake tests

Author: PeterCalifano

AGENTS.md

@@ -11,6 +11,33 @@ Keep ROS-related changes confined to `ros2/` plus the documented root helpers, d
 <!-- ros2-overlay-end -->
 For python: Use python standard >= 3.12, matplotlib is the backend for most plots, but for images PIL and opencv are also used. For any statistics-like plot prefer seaborn, my default choice. Use pytorch for machine learning applications, supported by sklearn. Function names beings with Capital letter, snake case, methods not. Classes Similarly. Internal methods (not public API) must start with _, local scope variables end with _. All methods of classes shall start with small letter. Prefer dataclasses instead of dicts and enums instead of Literals if more than two entries. Type Hints Must Always Be Present. Onnx Export Compatibility Is Generally Required. When Writing New Classes Or Functions, A Runnable Example Should Always Be Present With Output To Show Results.
 For C++/CUDA: C++17 and C++20 are the core standards. CUDA mainly >12.6. Answers should be on point without too many digressions, technical (for intermediate and advanced users) but simple enough to explain the concepts. Prefer using concepts over SFINAE. Unit tests using Catch2. Check files to see convention of names. Prefer Classes over structs.
+
+### CMake and derived-project test policy
+
+Do not copy template-conformance CMake verifiers into a derived project merely
+because the donor template has them. In particular, do not register tests that
+recursively configure and rebuild the same derived project inside its ordinary
+CTest suite when a fresh configure/build/install/consumer command or CI job
+already proves the contract.
+
+For a derived project:
+
+- prefer Catch2 or pytest for project runtime behavior;
+- validate CMake options, headless/full feature matrices, installation,
+  packaging, and external consumers through explicit fresh out-of-tree
+  acceptance commands owned by local CI;
+- use disposable consumer projects outside the normal test build when nested or
+  installed consumption must be proven;
+- add a permanent CMake-script test only when it is lightweight, target-owned,
+  isolates behavior unavailable through an existing target/test, and does not
+  recursively rebuild the project;
+- never import `VerifyTemplateProject*` or other donor self-validation tests as
+  product tests.
+
+The template repository may retain broader conformance tests because it owns
+generic generation and tailoring behavior. That exception does not make those
+tests part of the derived-project contract.
+
 For MATLAB: Use classes a lot also in MATLAB, with a python style, but do it only when it makes sense. Functions in MATLAB are often more efficient. Evaluate whether it makes sense to have stateful implementation. Use "self" instead of "obj". All variables names must specify the datatype of the variable since MATLAB does not (hungarian notation). The following list applies: d for double, f for float, b for bool, str for struct and not for strings, char for strings and chars, ui8 for uint8, i8 for int8.  All the other integers are similar to the latter. Specify "obj" as prefix if an object, cell if a cell, table if a table; "bus_" if a Simulink bus. The names are always in Pascal case including the prefix, for instance ui8MyVariable. Never nest functions definitions within other functions, always do them separate or at most in the same file (after the main function implementation). Add them as local in the same function file only when not re-used elsewhere, otherwise prefer a single implementation. Function names and static methods of classes starts with Capital letter. Local functions names ends with underscore meaning "private". Names of variables must be explicative and tell what the variable does. Short names are not allowed unless "very local in scope". Use underscore for those variables and preferably Tmp within the name. For codes that are intended to be algorithms of some kind (e.g. not plots or things to run on the host PC), make them always MATLAB codegen safe (especially if codegen directive is used). In that case names should be limited to 31 chars. Add the same template of doc to functions as below and always specify arguments-end block for input and output:
 %% SIGNATURE
 %

doc/developments/derived_project_upgrade_agent_guidelines.md

@@ -118,7 +118,9 @@ Before any edit:
 - record generated artifacts or package-consumer checks that define success;
 - identify user-facing APIs, options, names, and workflows that must remain
   stable;
-- add a focused red guard first when the donor delta fixes a reproducible bug.
+- add a focused red guard first when the donor delta fixes a reproducible bug,
+  but do not turn a one-time feature-matrix or consumer acceptance build into a
+  recursive test in the target's ordinary CTest suite.
 
 After the update:
 
@@ -131,6 +133,18 @@ After the update:
 - test installed or packaged consumption when the update touches exports,
   metadata, headers, or dependency flow.
 
+Keep template conformance and target acceptance separate:
+
+- do not copy donor `tests/cmake/VerifyTemplateProject*` files into a derived
+  repository;
+- do not register recursive configure/build/install tests in ordinary target
+  CTest when explicit fresh acceptance commands or CI already own the contract;
+- use disposable nested/build-tree/install-tree consumers outside the normal
+  test build;
+- add a permanent CMake-script test only when it is lightweight, target-owned,
+  non-recursive, and covers behavior unavailable through Catch2, pytest, an
+  existing target, or the acceptance matrix.
+
 If the baseline is already red, record the exact failure set before proceeding.
 The update may continue only when the failure is unrelated and the user agrees.
 Do not report the target as green; report that no new regression was introduced
@@ -252,6 +266,8 @@ considered.
 - Confirm which donor tests are template-only and which contracts must survive
   in a derived project.
 - Do not treat template-validation workflows as project workflows.
+- Translate applicable donor CMake conformance into target acceptance commands;
+  do not copy recursive verifier scripts into target CTest.
 
 ### Stage 1 - Baseline the target and capture tailoring
 
@@ -272,7 +288,9 @@ considered.
 - List each applicable donor delta and its classification.
 - Name exact target files and line/semantic anchors.
 - Define allowed and frozen surfaces.
-- Add red-green tests before implementation where practical.
+- Add red-green tests before implementation where practical. For build-system
+  feature matrices and consumer behavior, use a recorded failing acceptance
+  command rather than a permanent recursive CTest.
 - Order changes so every commit candidate is internally coherent and testable.
 - Obtain user approval when the plan changes architecture, dependencies, public
   API, release behavior, or established tailoring.

doc/template_usage.md

@@ -134,7 +134,21 @@ Only the main project configures documentation, tests, examples, wrappers, and g
 
 ## Tests
 
-Use Catch2 for compiled tests, pytest for Python tests, and CTest as the common runner. Put compiled tests in `test*.cpp` or `test*.cu` files and Python tests in `test*.py` files. Add narrow CMake-script tests under `tests/cmake/` when the behavior is about configuration, installation, generated files, CI YAML, or documentation output rather than runtime C++ behavior.
+Use Catch2 for compiled tests, pytest for Python tests, and CTest as the common
+runner. Put compiled tests in `test*.cpp` or `test*.cu` files and Python tests in
+`test*.py` files.
+
+The template repository uses `tests/cmake/` for template-owned conformance,
+tailoring, and generation checks. Do not copy those verifiers into a tailored
+project. A derived project should prove configuration, feature matrices,
+installation, packaging, and external consumption with explicit fresh
+out-of-tree commands in its acceptance/CI matrix. Do not make ordinary CTest
+recursively configure and rebuild the same project when CI already owns that
+behavioral gate.
+
+A permanent derived-project CMake-script test is justified only when it is
+lightweight, project-specific, cannot be covered by an existing runtime target
+or acceptance command, and does not recursively rebuild the project.
 
 Run focused checks during development. Prefer `ctest --test-dir <build>` so the
 same command works from the repository root, local scripts, and CI jobs:
@@ -202,6 +216,9 @@ The script replaces `template_project::logging` with the required project namesp
 
 It also removes the root CMake hook for the template MATLAB regression helper and rewrites `tests/CMakeLists.txt` so only starter project unit tests remain registered.
 
+This cleanup boundary is intentional: template CMake conformance tests remain
+owned by the donor/testfield validation harness, not by the tailored product.
+
 ### Workflow materialization
 
 The runnable `.github/workflows/*.yml` files in this repository validate the

doc/testing_and_ci.md

@@ -16,6 +16,24 @@ Compiled tests are discovered from `test*.cpp` and `test*.cu` files and run with
 Catch2. Python tests are discovered from `test*.py` files and registered as
 normal CTest entries that execute `python -m pytest -q <test-file>`.
 
+### Template conformance versus derived-project acceptance
+
+The template's default CTest suite includes conformance checks for generic
+tailoring, generated files, workflows, and package behavior. Those checks are
+template-maintainer infrastructure and are removed by normal tailoring.
+
+Do not reproduce them as recursive CMake tests in a derived project. In
+particular, ordinary derived-project CTest must not configure and rebuild the
+same project again merely to cover an option combination, headless build,
+installation, package archive, or consumer build. Put those gates in explicit
+fresh out-of-tree acceptance commands or CI jobs, where build ownership,
+prerequisites, logs, and artifacts are visible.
+
+Permanent CMake-script tests in a derived project are limited to lightweight,
+project-owned checks that cannot be expressed through Catch2, pytest, an
+existing build target, or the acceptance matrix. They must not import
+`VerifyTemplateProject*` scripts or create nested full-project builds.
+
 Catch2 remains the unit-test framework for the core C++ and CUDA project. Tests
 inside ROS packages are the deliberate exception: they use
 `ament_cmake_gtest` so test targets and results participate in the ament/colcon