add Reference Material

.github/workflows/parser-reference-guard.yml

@@ -46,8 +46,8 @@ jobs:
             exit 0
           fi
 
-          C_DOC="docs/c_parser.md"
-          FORTRAN_DOC="docs/fortran_parser.md"
+          C_DOC="docs/developer/c-parser-reference.md"
+          FORTRAN_DOC="docs/developer/fortran-parser-reference.md"
 
           C_DOC_CHANGED=false
           FORTRAN_DOC_CHANGED=false
@@ -64,29 +64,15 @@ jobs:
 
           while IFS= read -r changed_file; do
             case "$changed_file" in
-              c_parser/*|x2py/c_parser/*|tests/parser/c/*|tests/data/c/*|tests/parser/test_c_standard_type_probe.py)
+              c_parser/*|x2py/c_parser/*|tests/parser/c/*|tests/parsing/c/*|tests/data/c/*|tests/probes/test_c_types.py)
                 C_PARSER_CHANGED=true
                 ;;
-              fortran_parser/*|x2py/fortran_parser/*|tests/parser/fortran/*|tests/data/fortran/*)
-                FORTRAN_PARSER_CHANGED=true
-                ;;
-              tests/parser/test_declaration_and_interface_edges.py|\
-              tests/parser/test_error_handling.py|\
-              tests/parser/test_fortran_fixture_suite.py|\
-              tests/parser/test_fortran_json_sanity.py|\
-              tests/parser/test_fortran_parser_regression_contracts.py|\
-              tests/parser/test_fortran_type_probe.py|\
-              tests/parser/test_function_header_parsing.py|\
-              tests/parser/test_parser_developer_tutorial.py|\
-              tests/parser/test_parser_public_entrypoints.py|\
-              tests/parser/test_procedure_and_type_parsing.py|\
-              tests/parser/test_project_scope_models.py|\
-              tests/parser/test_scope_handling.py)
+              fortran_parser/*|x2py/fortran_parser/*|tests/parser/fortran/*|tests/parsing/fortran/*|tests/data/fortran/*|tests/probes/test_fortran_types.py)
                 FORTRAN_PARSER_CHANGED=true
                 ;;
               tests/parser/conftest.py|\
-              tests/parser/test_cli.py|\
-              tests/parser/test_preprocessing_cli.py|\
+              tests/cli/*|\
+              tests/pipeline/preprocessing/*|\
               x2py/preprocessing.py)
                 SHARED_PARSER_CHANGED=true
                 ;;

.github/workflows/quality.yml

@@ -183,13 +183,20 @@ jobs:
             test_paths=(tests)
           else
             test_paths=(
-              tests/parser
-              tests/property
+              tests/architecture
+              tests/benchmarks
+              tests/cli
+              tests/codegen
+              tests/docs
+              tests/lowering
+              tests/naming
+              tests/parsing
+              tests/pipeline
+              tests/probes
+              tests/runtime
               tests/semantics
-              tests/pyi
               tests/tools
-              tests/benchmarks
-              tests/test_naming_policy.py
+              tests/types
               tests/wrapper/fortran/arrays
               tests/wrapper/fortran/build_from_pyi
               tests/wrapper/fortran/build_from_source
@@ -212,9 +219,13 @@ jobs:
 
           if [[ "${{ matrix.python-version }}" == "3.12" && "$X2PY_COVERAGE_REQUESTED" == "true" ]]; then
             COVERAGE_PROCESS_START="${{ github.workspace }}/pyproject.toml" \
-              python -m coverage run -m pytest -q --randomly-seed=1 "${test_paths[@]}"
+              python -m coverage run -m pytest -q --randomly-seed=1 \
+                -o junit_family=legacy \
+                --junitxml="$RUNNER_TEMP/pytest-results.xml" "${test_paths[@]}"
           else
-            python -m pytest -q --randomly-seed=1 "${test_paths[@]}"
+            python -m pytest -q --randomly-seed=1 \
+              -o junit_family=legacy \
+              --junitxml="$RUNNER_TEMP/pytest-results.xml" "${test_paths[@]}"
           fi
       - name: Upload coverage data
         if: matrix.python-version == '3.12' && ((github.event_name == 'push' && github.ref == 'refs/heads/main') || (github.event_name == 'pull_request' && contains(github.event.pull_request.labels.*.name, 'run-coverage')) || (github.event_name == 'workflow_call' && inputs.coverage))
@@ -224,6 +235,9 @@ jobs:
           path: .coverage.*
           include-hidden-files: true
           if-no-files-found: error
+      - name: Summarize failed pytest nodes
+        if: failure()
+        run: python tools/print_pytest_failures.py "$RUNNER_TEMP/pytest-results.xml"
 
   coverage-report:
     name: Coverage Report

AGENTS.md

@@ -17,6 +17,20 @@ When updating tests, remove obsolete tests that only assert removed/old implemen
 
 Before `x2py/semantics/ir2ast.py` runs, the post-IR policy stage must have completed every semantic decision needed by wrapper generation, including object kind, ownership, transfer, destruction, mutability/writeback, nullability, output projection, release responsibility, contract-value storage mode (`stack`, `heap`, or `alias`), getter behavior, native setter assignment, and Python setter exposure. Bridge and binding generators may only dispatch from those completed decisions into small named implementation methods. They must not infer or override semantic policy from datatype, `intent`, dotted-variable shape, `is_alias`, or local memory checks, and they must not contain a fallback that silently chooses a different behavior. When such a decision is found in bridge or binding code, remove it there and move it into post-IR policy completion. Backend-local helper temporaries may still be created inside the selected implementation method because they are emitted-code details, not semantic policy.
 
+After every implementation task, the final summary must include a breakdown of
+the stages that actually changed. Relevant stages include parsing, semantic IR
+construction, post-IR policy completion, IR-to-AST/lowering, binding
+generation, bridge generation, compilation/build integration, and
+documentation. For each changed stage, state what behavior or representation
+changed there. Do not include unchanged stages or empty stage headings. Also
+identify the tests that were added or updated, where they live, what behavior
+they cover, and the relevant verification results. When the implementation
+reused or improved an existing code path, name that path and explain how it was
+reused or changed. The stage breakdown is a required part of the summary, not a
+restriction on the rest of it: add any relevant cross-cutting outcomes,
+decisions, risks, limitations, verification gaps, or handoff details outside
+the stage breakdown when they help explain the implementation.
+
 Changes in `x2py/semantics/ir2ast.py`, `x2py/codegen/`, and `x2py/compiling/` are separated from the rest of the project. For modifications limited to those areas, run only `tests/wrapper` tests unless a broader test run is explicitly requested.
 Do not run LAPACK wrapper tests locally unless the user explicitly asks for them. Local verification may run everything else, including BLAS-only real-library tests; leave LAPACK coverage to GitHub Actions by default.
 Do not run the full coverage workflow for routine changes. Run focused tests plus the required static-analysis suite. Reserve the complete CI-style coverage workflow for explicit pre-merge or pull-request verification, or when the user specifically requests it.
@@ -25,7 +39,7 @@ For documentation-only changes that do not modify executable Python code,
 runtime behavior, build configuration, or test logic, do not run the complete
 static-analysis suite by default. Run the focused documentation checks and
 whitespace check instead:
-- `python3 -m pytest -q tests/tools/test_documentation_examples.py tests/tools/test_documentation_structure.py`
+- `python3 -m pytest -q tests/docs/test_examples.py tests/docs/test_structure.py`
 - `git diff --check`
 Run the complete static-analysis suite when code, tests, build behavior, or
 tooling configuration changes, or when explicitly requested for pre-merge or

CONTRIBUTING.md

@@ -15,7 +15,7 @@ when parser-related files change.
   `tests/data/c/`, update `docs/c_parser.md` when the change affects the
   documented feature inventory, public API, diagnostics, fixtures, semantic
   handoff, or maintenance workflow. The guard also treats
-  `tests/parser/test_c_standard_type_probe.py` as C parser related.
+  `tests/probes/test_c_types.py` as C parser related.
 - **Fortran parser changes**: if you change `x2py/fortran_parser/`,
   `tests/parser/fortran/`, or `tests/data/fortran/`, update
   `docs/fortran_parser.md` when the change affects the documented feature