Add the PLAN-623 branch-local citation evidence contract and the CT-001 detector-sweep packet

.github/workflows/ci_macos.yml

@@ -41,13 +41,25 @@ jobs:
     steps:
       - name: Checkout
         uses: actions/checkout@v6
+        with:
+          # check-citation-evidence (via check-lint) verifies packet
+          # target commits against the local object store; a shallow
+          # clone cannot answer whether a historical commit exists.
+          fetch-depth: 0
 
       - name: Setup pixi
         uses: prefix-dev/setup-pixi@v0.9.6
         with:
           cache: true
           pixi-bin-path: ${{ runner.temp }}/pixi/bin/pixi
 
+      - name: Fetch citation packet target refs
+        # Squash merges retire topic-branch commits from branch
+        # history; the surviving refs/pull/N/head namespace is not
+        # covered by fetch-depth: 0, so fetch the refs the packets
+        # actually name.
+        run: pixi run python scripts/check_citation_evidence.py --fetch-target-refs
+
       - name: Check Lint
         run: |
           DART_VERBOSE=ON \

.github/workflows/ci_ubuntu.yml

@@ -110,6 +110,11 @@ jobs:
     steps:
       - name: Checkout
         uses: actions/checkout@v6
+        with:
+          # check-citation-evidence (via check-lint) verifies packet
+          # target commits against the local object store; a shallow
+          # clone cannot answer whether a historical commit exists.
+          fetch-depth: 0
 
       - name: Setup pixi
         uses: prefix-dev/setup-pixi@v0.9.6
@@ -122,6 +127,13 @@ jobs:
           packages: libgl1-mesa-dev libglu1-mesa-dev xvfb
           version: "2"
 
+      - name: Fetch citation packet target refs
+        # Squash merges retire topic-branch commits from branch
+        # history; the surviving refs/pull/N/head namespace is not
+        # covered by fetch-depth: 0, so fetch the refs the packets
+        # actually name.
+        run: pixi run python scripts/check_citation_evidence.py --fetch-target-refs
+
       - name: Check Lint
         run: |
           DART_VERBOSE=ON \

.github/workflows/ci_windows.yml

@@ -55,6 +55,11 @@ jobs:
     steps:
       - name: Checkout
         uses: actions/checkout@v6
+        with:
+          # check-citation-evidence (via check-lint) verifies packet
+          # target commits against the local object store; a shallow
+          # clone cannot answer whether a historical commit exists.
+          fetch-depth: 0
 
       - name: Setup pixi
         uses: prefix-dev/setup-pixi@v0.9.6
@@ -107,6 +112,13 @@ jobs:
           }
           cmd.exe /c exit 0
 
+      - name: Fetch citation packet target refs
+        # Squash merges retire topic-branch commits from branch
+        # history; the surviving refs/pull/N/head namespace is not
+        # covered by fetch-depth: 0, so fetch the refs the packets
+        # actually name.
+        run: pixi run python scripts/check_citation_evidence.py --fetch-target-refs
+
       - name: Check Lint
         run: |
           pixi run check-lint

CHANGELOG.md

@@ -751,6 +751,17 @@
 
 * Tests
 
+  * Add the branch-local citation-claim evidence contract (PLAN-623): a
+    machine-checked `release-6.20` claims manifest under
+    `docs/design/dart6_citation_driven_contact_trust/`, a fail-closed
+    `pixi run check-citation-evidence` gate (missing commit, scene digest,
+    requested/resolved detector or solver identity, command, ensemble,
+    disposition, claim boundary, or typed-unsupported metrics fail
+    validation, with a permanent intentionally incomplete negative-control
+    packet), and the first CT-001 rolling-direction evidence packet sweeping
+    the available collision detectors. Additive evidence tooling only; no
+    library, API, ABI, or default behavior change.
+
   * Force the ASan and required assertions-enabled builds to run without
     OpenSceneGraph, and require exact-candidate optional-dependency and Gazebo
     integration evidence before DART 6 releases:

docs/design/README.md

@@ -16,6 +16,7 @@ For cross-bucket placement decisions, use
 | File | Purpose |
 | --- | --- |
 | [`dart6_ai_infra.md`](dart6_ai_infra.md) | Release-branch AI documentation, model-evolution, and visual-evidence decisions within DART 6 compatibility constraints. |
+| [`dart6_citation_driven_contact_trust.md`](dart6_citation_driven_contact_trust.md) | PLAN-623 citation contact trust on the LTS branch: branch-local claims manifest, fail-closed evidence packets, row set, and fix policy under the compatibility contract. |
 | [`dart6_collision_backends.md`](dart6_collision_backends.md) | Current DART 6.20 collision-backend architecture, compatibility boundary, downstream gz obligations, and later backend lifecycle. |
 | [`dart6_deformable_body.md`](dart6_deformable_body.md) | DART 6.20 deformable-body compatibility, paper scope, performance evidence, and collision-backend decisions. |
 

docs/design/dart6_citation_driven_contact_trust.md

@@ -0,0 +1,185 @@
+# DART 6.20 Citation-Driven Contact Trust
+
+## Status
+
+Durable compatibility and evidence contract for `release-6.20`. Active
+implementation state lives in
+`docs/dev_tasks/dart6_citation_contact_trust/`. The DART 7 long-term owner is
+`docs/design/contact_trust_and_observability.md` on `main`.
+
+## Purpose
+
+DART 6.20 should answer historical and current claims about DART 6 with
+source-faithful reproductions, permanent tests/benchmarks, and honest
+dispositions while preserving the LTS contract. This branch may improve
+existing collision, contact, solver, sleeping, parser, and diagnostic behavior
+when a defect is demonstrated, but it is not a vehicle for DART 7 architecture
+or new public solver families.
+
+## Compatibility boundary
+
+All work preserves unless explicitly authorized otherwise:
+
+- C++17 and pybind11;
+- installed headers, symbols, class layouts, components, and parser surfaces;
+- FCL `PRIMITIVE` as the built-in default;
+- real FCL, Bullet, ODE, and DART-owned collision backends and factory keys;
+- OSG and consolidated `dart-demos`;
+- default simulation behavior for unaffected scenes;
+- Gazebo/gz-physics/gz-sim compatibility;
+- public `collision::Contact` and constraint/contact-surface semantics.
+
+`main` is reference evidence only. Do not import C++23, nanobind, EnTT World
+storage, DART 7 solver/backend APIs, or generated DART 7 workflows.
+
+## Allowed work
+
+- Source-bound reproductions of citation, benchmark, and issue claims.
+- Additive tests, benchmarks, demos, scripts, and evidence schemas.
+- Internal or opt-in diagnostics with compile-time/runtime-zero common-path
+  overhead where the branch contract requires it.
+- Implementation-local correctness, determinism, allocation, and performance
+  fixes with negative controls.
+- Additive non-virtual helpers only after ABI/source review.
+- Documentation clarifying impulse/force/wrench semantics without changing
+  established ABI.
+- Separate `main` fixes for defects shared across branches.
+
+## Excluded work
+
+- New exact-cone/NCP, IPC, VBD/AVBD, differentiable, batch-World, rod/shell, or
+  biomechanics solver architecture.
+- Public model/state/contact redesign.
+- Default detector or solver changes.
+- Removal or facade replacement of FCL/Bullet/ODE.
+- New required dependencies or language/binding/rendering floor changes.
+- Broad refactors justified only by DART 7 cleanliness.
+- Silent contact smoothing or changed downstream force conventions.
+
+## Owner integration
+
+Before creating new fixtures or task owners, audit and reuse:
+
+- PLAN-621 and `docs/dev_tasks/dart6_performance_generalization/`;
+- PLAN-622 and `docs/dev_tasks/dart6_deformable_body_performance/`;
+- `docs/design/dart6_collision_backends.md`;
+- existing DART 6 benchmark, capture, evidence, and AI verification tooling;
+- current open PRs/issues and any newer completion/retirement state.
+
+A corpus row already owned by PLAN-621/622 stays there. The citation task points
+to its evidence and does not copy the implementation checklist.
+
+## Claim and evidence contract
+
+Use the same stable claim IDs and dispositions as DART 7, but every packet is
+explicitly `release-6.20` and records (enforced by
+`scripts/check_citation_evidence.py` — this list matches the enforced
+schema, not an aspiration beyond it):
+
+- exact target commit plus the runnable durable fetch command;
+- scene identity: digest-bound parameters (source model, license, and
+  conversion provenance are recorded WHEN an external model asset is used;
+  procedurally built primitive scenes carry their full construction in
+  `scene.parameters` and have no external asset to attribute);
+- detector, constraint solver, timestep, iterations, threads, and defaults
+  (typed unsupported where the branch exposes no accessor);
+- ensemble (verified repeats, or object sweep points/seeds each bound to
+  their own recorded rows) and a named measurement window;
+- contact/trajectory hashes, penetration, energy where available;
+- exact reproducible commands (build step included) and host validity,
+  with measured timing forbidden when the host is not
+  performance-controlled;
+- disposition, claim boundary, and limitations;
+- Gazebo/gz relevance, recorded per packet in its limitations or notes
+  when a downstream-visible path is touched;
+- digest-bound review evidence.
+
+If DART 6 lacks a comparable metric, record it as unsupported or derive it in
+the harness without changing public runtime APIs. Never encode unsupported as
+numeric zero.
+
+## Contact semantics
+
+DART 6 public compatibility constrains API changes, but evidence must still
+distinguish:
+
+- collision query geometry;
+- solver impulse;
+- legacy per-step `Contact.force`/wrench data;
+- interval-average or filtered analysis values;
+- downstream Gazebo contact sensor transforms and sign/ownership.
+
+Tests should pin object ordering, normal convention, point/frame transforms,
+force/wrench sign, timestep dependence, reset/clone behavior, and downstream
+conversion where applicable. Do not silently reinterpret released fields.
+
+New analysis helpers should remain in tests/examples/scripts or additive
+non-virtual APIs after compatibility review.
+
+## Initial DART 6 rows
+
+The durable row set for this branch (unordered — working priority lives with
+the active task state, not here):
+
+- the completed `3k_shapes` and sleeping/collision performance campaign
+  (audit/guard);
+- rolling/friction-direction behavior across FCL, DART, Bullet, and ODE where
+  supported;
+- dense inelastic/elastic contact finite-state and failure grids;
+- heel-strike/toe-off raw impulse and legacy force/wrench interpretation;
+- contact normal/object ordering and Gazebo wrench sensor regressions;
+- high mass-ratio stacks/manipulation and current solver fallback behavior;
+- existing PLAN-622 soft-contact robustness rows using perturbation ensembles
+  (these contribute evidence without expanding the cap).
+
+The cap is six common fixture families with dispositions. The working order
+in which rows are attacked is mutable state and is owned by the PLAN-623
+task home (`docs/dev_tasks/dart6_citation_contact_trust/README.md`) with the
+branch manifest recording live lane status; this document records only which
+rows exist and why.
+
+## Fix policy
+
+A DART 6 behavioral fix requires:
+
+- baseline reproduction on a current clean release base;
+- root cause;
+- smallest compatibility-safe change;
+- regression that fails before and passes after;
+- state/contact/rest hash or explicit re-baseline;
+- no unrelated default or backend changes;
+- ABI/header/component/package audit when near a public boundary;
+- `pixi run -e gazebo test-gz` for collision/constraint/World/downstream work;
+- a separate DART 7 issue/PR assessment.
+
+Performance gains cannot come from lost contacts, changed sleeping, cap hits,
+skipped work that remains physically required, or a different model without
+being labeled non-equivalent.
+
+## Diagnostics and overhead
+
+Diagnostics are opt-in and preferably test/harness-side. Any library
+instrumentation must:
+
+- preserve public class layout and vtables;
+- be default-off when it adds work or state;
+- compile out or have proved negligible common-path cost as appropriate;
+- avoid global registries, locks, or heap allocation on every solve/step;
+- report actual detector/solver/fallback and unsupported metrics honestly.
+
+## Verification
+
+Every slice runs:
+
+- `pixi run lint`;
+- focused build and C++/dartpy tests;
+- relevant benchmarks with raw rows and validity checks;
+- deterministic repeats/ensembles;
+- visual evidence through the branch OSG/demos path when visible;
+- `pixi run -e gazebo test-gz` when downstream-sensitive;
+- two clean independent or role-separated reviews;
+- explicit changelog decision.
+
+Before completion, promote durable facts to this design, existing collision,
+testing, profiling, user, or release owners, then remove the dev-task folder in
+the completing PR.