phaseprobe 0.2.0__tar.gz → 0.3.0__tar.gz

{phaseprobe-0.2.0 → phaseprobe-0.3.0}/.github/workflows/ci.yml

@@ -50,8 +50,8 @@ jobs:
       - run: python -m ruff check .
       - run: python -m mypy src tests
       - run: python -m pytest --cov=phaseprobe --cov-report=term
-      - run: python -m phaseprobe perturb --config examples/scipy/lorenz-negative.json
-      - run: python -m phaseprobe check --config examples/scipy/predator-prey.json
+      - run: python -m phaseprobe perturb --example scipy-lorenz-negative
+      - run: python -m phaseprobe check --example scipy-predator-prey
 
   package-and-hygiene:
     runs-on: ubuntu-latest
@@ -65,14 +65,10 @@ jobs:
       - run: python -m build
       - run: python -m twine check dist/*
       - run: python scripts/audit_package.py
-      - run: python -m venv .cache/packed-smoke
-      - run: .cache/packed-smoke/bin/python -m pip install dist/*.whl
-      - run: .cache/packed-smoke/bin/python -m phaseprobe --version
-      - run: .cache/packed-smoke/bin/python -m phaseprobe scan --example logistic-negative
-      - run: .cache/packed-smoke/bin/python -c "import importlib.util; assert importlib.util.find_spec('numpy') is None; assert importlib.util.find_spec('scipy') is None"
-      - run: python -m venv .cache/scipy-smoke
-      - run: .cache/scipy-smoke/bin/python -m pip install "$(find dist -name '*.whl')[scipy]"
-      - run: .cache/scipy-smoke/bin/python -m phaseprobe check --config examples/scipy/predator-prey.json
+      - run: >-
+          python scripts/verify_artifacts.py
+          --dist-dir dist
+          --work-root "${RUNNER_TEMP}/phaseprobe artifact gate"
       - run: python scripts/check_links.py
       - run: python scripts/hygiene.py
       - uses: actions/upload-artifact@v4
@@ -80,3 +76,21 @@ jobs:
           name: phaseprobe-packages
           path: dist/*
           if-no-files-found: error
+
+  windows-artifact-install:
+    name: artifact install / windows / Python 3.12
+    runs-on: windows-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+      - run: python -m pip install --upgrade pip build twine
+      - run: python -m build
+      - run: python -m twine check dist/*
+      - run: python scripts/audit_package.py
+      - run: >-
+          python scripts/verify_artifacts.py
+          --dist-dir dist
+          --work-root "$env:RUNNER_TEMP\phaseprobe artifact gate"

phaseprobe-0.3.0/.github/workflows/publish-pypi.yml

@@ -0,0 +1,166 @@
+name: Publish an existing GitHub release to PyPI
+
+on:
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: Immutable release tag (for example, v0.2.1)
+        required: true
+        type: string
+      version:
+        description: Expected package version (for example, 0.2.1)
+        required: true
+        type: string
+      commit:
+        description: Expected 40-character commit for the tag
+        required: true
+        type: string
+      wheel_sha256:
+        description: Expected SHA-256 for the wheel release asset
+        required: true
+        type: string
+      sdist_sha256:
+        description: Expected SHA-256 for the source release asset
+        required: true
+        type: string
+
+permissions: {}
+
+concurrency:
+  group: pypi-${{ inputs.tag }}
+  cancel-in-progress: false
+
+jobs:
+  verify:
+    name: Verify immutable release assets
+    if: >-
+      github.repository == 'aliengineering-byte/phaseprobe' &&
+      github.ref == 'refs/heads/main'
+    runs-on: ubuntu-latest
+    permissions: {}
+    steps:
+      - name: Download and verify the selected release
+        env:
+          TAG: ${{ inputs.tag }}
+          VERSION: ${{ inputs.version }}
+          EXPECTED_COMMIT: ${{ inputs.commit }}
+          WHEEL_SHA256: ${{ inputs.wheel_sha256 }}
+          SDIST_SHA256: ${{ inputs.sdist_sha256 }}
+        shell: bash
+        run: |
+          set -euo pipefail
+
+          [[ "$TAG" =~ ^v[0-9]+\.[0-9]+\.[0-9]+$ ]]
+          [[ "$VERSION" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]
+          [[ "$TAG" == "v$VERSION" ]]
+          [[ "$EXPECTED_COMMIT" =~ ^[0-9a-f]{40}$ ]]
+          [[ "$WHEEL_SHA256" =~ ^[0-9a-f]{64}$ ]]
+          [[ "$SDIST_SHA256" =~ ^[0-9a-f]{64}$ ]]
+
+          repository_url="https://github.com/${GITHUB_REPOSITORY}.git"
+          tag_refs="$(git ls-remote "$repository_url" "refs/tags/$TAG" "refs/tags/$TAG^{}")"
+          direct_commit="$(awk -v ref="refs/tags/$TAG" '$2 == ref { print $1 }' <<<"$tag_refs")"
+          peeled_commit="$(awk -v ref="refs/tags/$TAG^{}" '$2 == ref { print $1 }' <<<"$tag_refs")"
+          resolved_commit="${peeled_commit:-$direct_commit}"
+          [[ -n "$resolved_commit" ]]
+          [[ "$resolved_commit" == "$EXPECTED_COMMIT" ]]
+
+          wheel="phaseprobe-$VERSION-py3-none-any.whl"
+          sdist="phaseprobe-$VERSION.tar.gz"
+          release_url="https://github.com/${GITHUB_REPOSITORY}/releases/download/$TAG"
+          mkdir dist
+          curl --fail --location --proto '=https' --tlsv1.2 \
+            --output "dist/$wheel" "$release_url/$wheel"
+          curl --fail --location --proto '=https' --tlsv1.2 \
+            --output "dist/$sdist" "$release_url/$sdist"
+          printf '%s  %s\n%s  %s\n' \
+            "$WHEEL_SHA256" "dist/$wheel" \
+            "$SDIST_SHA256" "dist/$sdist" | sha256sum --check --strict
+
+          python3 -m venv .twine-check
+          .twine-check/bin/python -m pip install --disable-pip-version-check 'twine==7.0.0'
+          .twine-check/bin/python -m twine check "dist/$wheel" "dist/$sdist"
+
+          python3 - "$VERSION" "dist/$wheel" "dist/$sdist" <<'PY'
+          import email
+          import sys
+          import tarfile
+          import zipfile
+
+          expected_version, wheel_path, sdist_path = sys.argv[1:]
+
+          with zipfile.ZipFile(wheel_path) as archive:
+              wheel_names = set(archive.namelist())
+              metadata_names = [
+                  name for name in wheel_names if name.endswith(".dist-info/METADATA")
+              ]
+              assert len(metadata_names) == 1, metadata_names
+              wheel_metadata = email.message_from_bytes(archive.read(metadata_names[0]))
+
+          with tarfile.open(sdist_path, "r:gz") as archive:
+              sdist_names = {member.name for member in archive.getmembers()}
+              metadata_members = [
+                  member
+                  for member in archive.getmembers()
+                  if member.isfile() and member.name.count("/") == 1 and member.name.endswith("/PKG-INFO")
+              ]
+              assert len(metadata_members) == 1, [member.name for member in metadata_members]
+              extracted = archive.extractfile(metadata_members[0])
+              assert extracted is not None
+              sdist_metadata = email.message_from_bytes(extracted.read())
+
+          sdist_roots = {name.split("/", 1)[0] for name in sdist_names if "/" in name}
+          assert len(sdist_roots) == 1, sorted(sdist_roots)
+          sdist_root = next(iter(sdist_roots))
+          source_prefix = f"{sdist_root}/src/phaseprobe/"
+          runtime_files = {
+              name.removeprefix(f"{sdist_root}/src/")
+              for name in sdist_names
+              if name.startswith(source_prefix)
+              and not name.endswith(".py")
+              and "__pycache__" not in name.split("/")
+          }
+          assert "phaseprobe/py.typed" in runtime_files
+          assert not runtime_files - wheel_names, sorted(runtime_files - wheel_names)
+
+          for metadata in (wheel_metadata, sdist_metadata):
+              assert metadata["Name"] == "phaseprobe"
+              assert metadata["Version"] == expected_version
+              assert metadata["Requires-Python"] == ">=3.10"
+              assert metadata["License-Expression"] == "Apache-2.0"
+              assert "scipy" in metadata.get_all("Provides-Extra", [])
+              requirements = metadata.get_all("Requires-Dist", [])
+              assert any(req.startswith("numpy") and "extra == 'scipy'" in req for req in requirements)
+              assert any(req.startswith("scipy") and "extra == 'scipy'" in req for req in requirements)
+              project_urls = metadata.get_all("Project-URL", [])
+              assert any(url.startswith("Source, https://github.com/aliengineering-byte/phaseprobe") for url in project_urls)
+          PY
+
+      - name: Store the verified distributions
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
+        with:
+          name: verified-distributions-${{ inputs.tag }}
+          path: dist/*
+          if-no-files-found: error
+          retention-days: 1
+
+  publish:
+    name: Publish verified distributions
+    needs: verify
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/phaseprobe/${{ inputs.version }}/
+    permissions:
+      id-token: write
+    steps:
+      - name: Retrieve the verified distributions
+        uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4
+        with:
+          name: verified-distributions-${{ inputs.tag }}
+          path: dist
+
+      - name: Publish distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # release/v1
+        with:
+          packages-dir: dist/

{phaseprobe-0.2.0 → phaseprobe-0.3.0}/.github/workflows/release.yml

@@ -20,13 +20,10 @@ jobs:
       - run: python -m build
       - run: python -m twine check dist/*
       - run: python scripts/audit_package.py
-      - run: python -m venv .cache/tag-core-smoke
-      - run: .cache/tag-core-smoke/bin/python -m pip install dist/*.whl
-      - run: .cache/tag-core-smoke/bin/python -m phaseprobe --version
-      - run: .cache/tag-core-smoke/bin/python -m phaseprobe scan --example logistic
-      - run: python -m venv .cache/tag-scipy-smoke
-      - run: .cache/tag-scipy-smoke/bin/python -m pip install "$(find dist -name '*.whl')[scipy]"
-      - run: .cache/tag-scipy-smoke/bin/python -m phaseprobe check --config examples/scipy/predator-prey.json
+      - run: >-
+          python scripts/verify_artifacts.py
+          --dist-dir dist
+          --work-root "${RUNNER_TEMP}/phaseprobe tagged artifact gate"
       - run: python scripts/hygiene.py
       - uses: actions/upload-artifact@v4
         with:

phaseprobe-0.3.0/CHANGELOG.md

@@ -0,0 +1,63 @@
+# Changelog
+
+All notable changes are documented here. PhaseProbe follows semantic versioning.
+
+## Unreleased
+
+- Added bounded offline `verify-evidence` validation for generated pytest evidence, replay
+  decisions, artifact hashes, safe relative paths, and the fixed regression template.
+- The unreleased package identity is now `0.3.0` for the new generated-evidence contract.
+- `generate-test` now writes a path-portable claim/decision evidence record that binds the
+  validated replay verdict to SHA-256 hashes of the copied fixture and generated pytest, the
+  exact reproduction command, PhaseProbe attribution, and explicit scientific limitations.
+- Identical generated evidence is idempotent; conflicting evidence is rejected without overwrite.
+- Invariant-only fixtures now use the narrower `simulation-replay-regression` claim kind, and the
+  unsigned evidence-integrity boundary is explicit.
+
+## 0.2.1 — 2026-08-31
+
+- Fixed Issue #4: all four SciPy quick-start configurations now ship inside the importable
+  package in both wheel and source distribution and load through `importlib.resources` as the
+  `scipy-lorenz`, `scipy-lorenz-negative`, `scipy-predator-prey`, and
+  `scipy-predator-prey-coarse` built-in examples.
+- Preserved the four exact former `examples/scipy/` config paths as narrow compatibility aliases
+  when no file exists at the requested path. Existing user files take precedence; matching is
+  case-sensitive and separator-portable, with no fuzzy or basename fallback.
+- Added actionable, versioned diagnostics for missing or malformed built-in resources without
+  changing arbitrary config-path or built-in-example behavior.
+- Added Linux and Windows Python 3.12 release gates that build, inspect, install, and exercise the
+  wheel and sdist outside the checkout with `PYTHONPATH` removed. The gate runs scan, replay,
+  generated pytest, SciPy Lorenz, SciPy predator–prey, `pip check`, and a dependency-free base
+  wheel check.
+- Added a source-derived runtime-resource audit and the PEP 561 `py.typed` marker.
+- Generated regression creation is now idempotent for identical evidence and rejects conflicting
+  files instead of silently overwriting them.
+- Added an analytic backward-time directional-event check while preserving all solver defaults
+  and the existing tolerance-based adaptive replay contract.
+
+## 0.2.0 — 2026-08-02
+
+- Added the backward-compatible `TrajectoryAdapter` protocol and shared engine dispatch; all v0.1
+  step adapters and examples continue unchanged.
+- Added optional `phaseprobe[scipy]` support with a typed public `SolveIVPAdapter`, controlled
+  evaluation grids, scalar/vector tolerances, methods, maximum step, named events, observables,
+  classifiers, invariants, invalid-value checks, bounded retention, and solver/environment evidence.
+- Added schema-v2 `exact` and `tolerance` replay while keeping schema-v1 exact fixtures readable.
+  Tolerance fixtures preserve state, observable, classifier, invariant threshold, grid, endpoint,
+  event, solver-success, version, and platform evidence without claiming byte-identical replay.
+- Added genuine SciPy Lorenz finite-time divergence and predator–prey first-integral examples,
+  negative controls, refinement evidence, HTML evidence, and generated pytest fixtures.
+- Added explicit safe-shape Python module/factory loading, core-without-SciPy tests, optional import
+  diagnostics, a Windows/Linux core/SciPy CI matrix, current SciPy audit, security/limitations docs,
+  demo assets, and an unposted upstream visibility proposal.
+- Base installation remains dependency-free. NumPy and SciPy are optional; no PyPI publication was
+  performed.
+
+## 0.1.0 — 2026-08-01
+
+- Added `scan`, `perturb`, `check`, `replay`, `generate-test`, and `report` commands.
+- Added typed adapters for logistic map, Lorenz, Lotka–Volterra predator–prey, and a mutually repressing genetic toggle.
+- Added deterministic seeds, canonical configuration, fixed-step execution, invalid-integration diagnostics, capped trace retention, and exact trace hashes.
+- Added transition brackets, bounded initial-state search, repeatability confirmation, replay fixtures with integrity hashes, and fixed-template pytest generation.
+- Added terminal, versioned JSON, and self-contained offline HTML evidence.
+- Added Windows/Linux CI, packaging and packed-install checks, documentation/hygiene gates, and repository-native demo assets.

{phaseprobe-0.2.0 → phaseprobe-0.3.0}/CITATION.cff

@@ -4,8 +4,7 @@ title: "PhaseProbe"
 type: software
 authors:
   - name: "Ali"
-version: 0.2.0
-date-released: 2026-08-02
+version: 0.3.0
 url: "https://github.com/aliengineering-byte/phaseprobe"
 repository-code: "https://github.com/aliengineering-byte/phaseprobe"
 license: Apache-2.0

{phaseprobe-0.2.0 → phaseprobe-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: phaseprobe
-Version: 0.2.0
+Version: 0.3.0
 Summary: Find reproducible qualitative simulation transitions and turn them into regression tests.
 Project-URL: Documentation, https://github.com/aliengineering-byte/phaseprobe#readme
 Project-URL: Issues, https://github.com/aliengineering-byte/phaseprobe/issues
@@ -43,7 +43,7 @@ Description-Content-Type: text/markdown
 Maintaining a simulation is risky when a tiny parameter or initial-condition change can cross a qualitative boundary while ordinary numeric assertions still look plausible. PhaseProbe runs a bounded, deterministic search, records exactly what it tested, and emits an offline report plus an executable pytest regression.
 
 ```console
-$ python -m pip install .
+$ pip install phaseprobe pytest
 $ phaseprobe scan --example logistic
 QUALITATIVE TRANSITION FOUND
 
@@ -62,15 +62,24 @@ $ python -m pytest -q tests/generated
 
 No API key, LLM, GPU, Docker, account, telemetry, network connection, or hosted service is required at runtime. PhaseProbe's base installation has no third-party runtime dependencies; NumPy and SciPy are isolated in the optional `scipy` extra.
 
+## Installation
+
+```bash
+pip install phaseprobe
+pip install "phaseprobe[scipy]"
+pip install pytest  # needed only to execute a generated regression test
+```
+
 ## Five-minute quick start
 
 Requires Python 3.10 or newer on Windows or Linux.
 
 ```bash
-python -m pip install .
+pip install phaseprobe pytest
 phaseprobe scan --example logistic
 phaseprobe replay .phaseprobe/runs/<run-id>/replay.json
 phaseprobe generate-test .phaseprobe/runs/<run-id>/replay.json
+phaseprobe verify-evidence tests/generated/logistic_map-pytest-evidence.json
 python -m pytest -q tests/generated
 phaseprobe report .phaseprobe/runs/<run-id>
 ```
@@ -90,22 +99,41 @@ Five-minute path:
 [![SciPy demo: solve_ivp evidence, tolerance replay, and generated pytest](assets/scipy-demo-static.png)](assets/scipy-demo.gif)
 
 The verified command transcript is [assets/scipy-demo-session.txt](assets/scipy-demo-session.txt),
-with a self-contained [HTML example report](examples/scipy/report.html).
+with a self-contained [HTML example report](examples/scipy/report.html). The following path starts
+from a clean environment and does not require a source checkout:
 
 ```bash
-python -m pip install "phaseprobe[scipy]"
-phaseprobe perturb --config examples/scipy/lorenz.json
-phaseprobe check --config examples/scipy/predator-prey.json
+python -m venv .venv
+# Linux: source .venv/bin/activate
+# Windows PowerShell: .venv\Scripts\Activate.ps1
+python -m pip install "phaseprobe[scipy]" "pytest==8.4.1"
+phaseprobe perturb --example scipy-lorenz
+phaseprobe check --example scipy-predator-prey
 phaseprobe replay .phaseprobe/runs/<run-id>/replay.json
 phaseprobe generate-test .phaseprobe/runs/<run-id>/replay.json
 python -m pytest -q tests/generated
 ```
 
+PhaseProbe 0.2.1 also recognizes the former Issue #4 command
+`phaseprobe perturb --config examples/scipy/lorenz.json` when that relative file is absent and
+loads the corresponding packaged example. This compatibility is limited to the four former
+`examples/scipy/` paths: an existing file always takes precedence, matching is case-sensitive,
+both slash styles are accepted, and unrelated missing paths remain errors. New documentation and
+automation should use the installed-safe `--example scipy-*` names.
+
 The Lorenz command searches a declared initial-`x` perturbation and reports only finite-time
-divergence evidence. `examples/scipy/lorenz-negative.json` is its short-window negative control.
-The predator–prey command checks the declared first integral with tightly resolved DOP853 settings;
-`examples/scipy/predator-prey-coarse.json` deliberately fails the same policy with loose RK23
-settings.
+divergence evidence and prints `FINITE-TIME TRAJECTORY DIVERGENCE FOUND`. Its installed
+short-window control is `--example scipy-lorenz-negative`. The predator–prey command checks the
+declared first integral with tightly resolved DOP853 settings and prints `CHECK POLICY PASSED`;
+`--example scipy-predator-prey-coarse` deliberately fails the same policy with loose RK23 settings.
+Each successful command writes a replay fixture and offline report below
+`.phaseprobe/runs/<run-id>/`.
+
+Run `phaseprobe perturb --help` or `phaseprobe check --help` to list installed example names. A
+missing packaged resource reports the PhaseProbe version and resource name. Adaptive SciPy replay
+compares the declared state, observable, invariant, endpoint, event, and retained-grid
+tolerances—it does not promise bitwise trajectory equality across platforms or dependency
+versions.
 
 For a direct Python API:
 
@@ -144,7 +172,8 @@ does not import it. See [the audited contract](docs/SCIPY_SOLVE_IVP_AUDIT.md),
 | `perturb` | Baseline/perturbed twin runs over bounded initial-state changes | Finding or no finding, exit `0` |
 | `check` | Execute a declared configuration policy for CI | Exit `1` only when policy fails |
 | `replay` | Validate fixture integrity and re-execute model, parameters, seed, initial state, tolerances, and retention | Declared `exact` or `tolerance` comparison passes |
-| `generate-test` | Validate and copy a fixture into a non-extensible pytest template | Executable test under `tests/generated/` |
+| `generate-test` | Validate and copy a fixture into a non-extensible pytest template without conflicting overwrites | Executable test under `tests/generated/` |
+| `verify-evidence` | Re-derive claims/replay decisions and validate bounded strict JSON, artifact hashes, paths, and the fixed template offline | Stable verified or invalid-input exit |
 | `report` | Regenerate terminal, versioned JSON, and self-contained offline HTML evidence | Local report files |
 
 Common options:
@@ -152,6 +181,7 @@ Common options:
 ```console
 phaseprobe scan --config examples/configs/logistic-scan.json
 phaseprobe perturb --example lorenz --json
+phaseprobe perturb --example scipy-lorenz --json
 phaseprobe check --example predator-prey
 phaseprobe scan --example logistic --fail-on-finding
 ```
@@ -166,6 +196,8 @@ Exit codes are stable: `0` completed, `1` declared policy or explicit `--fail-on
 | Lorenz system | `phaseprobe perturb --example lorenz` | Small initial separation exceeds the declared finite-time trajectory-distance threshold | Short window plus unreachable threshold reports no finding | [Lorenz, 1963](https://journals.ametsoc.org/view/journals/atsc/20/2/1520-0469_1963_020_0130_dnf_2_0_co_2.xml) |
 | Predator–prey | `phaseprobe check --example predator-prey` | Refined RK4 step preserves the analytic first integral within tolerance | Coarse step fails the invariant-drift policy | [Lotka, 1920](https://doi.org/10.1073/pnas.6.7.410) |
 | Genetic toggle | `phaseprobe perturb --example toggle` | Bounded initial-state perturbation reaches the opposite dominant state | Smaller declared range stays in the baseline basin | [Gardner, Cantor & Collins, 2000](https://www.nature.com/articles/35002131) |
+| SciPy Lorenz | `phaseprobe perturb --example scipy-lorenz` | DOP853 twin trajectories cross the declared finite-time distance threshold | `--example scipy-lorenz-negative` shortens the window | [Lorenz, 1963](https://journals.ametsoc.org/view/journals/atsc/20/2/1520-0469_1963_020_0130_dnf_2_0_co_2.xml) |
+| SciPy predator–prey | `phaseprobe check --example scipy-predator-prey` | Tight DOP853 settings preserve the declared first integral tolerance | `--example scipy-predator-prey-coarse` deliberately fails | [Lotka, 1920](https://doi.org/10.1073/pnas.6.7.410) |
 
 Each configuration records the seed, fixed integration/iteration settings, tolerances, burn-in, observation window, classification rule, refinement rule, invalid-state policy, and trace cap. See [examples/README.md](examples/README.md) for equations and interpretation.
 
@@ -188,6 +220,22 @@ manifest.json  sizes and SHA-256 hashes
 
 Model names used for generated test paths are sanitized. The generated source comes from a fixed template; configuration strings never become executable Python.
 
+`generate-test` validates the replay before writing anything. Alongside the fixed pytest template
+and copied fixture, it writes `<model>-pytest-evidence.json`: a path-portable claim/decision record
+containing repository/version attribution, the declared replay comparisons, SHA-256 hashes for
+both executable artifacts, the exact pytest command, and explicit scientific limitations.
+Run `phaseprobe verify-evidence <evidence.json>` before pytest to validate the strict schema,
+recompute the hashes, re-execute the replay policy, derive the claim/decision fields, and confirm
+that the regression still matches PhaseProbe's fixed template. Validation is offline, bounded to a
+1 MiB evidence document and 32 MiB per generated artifact, rejects duplicate keys and unsafe paths,
+and exits `2` for invalid input.
+The record is unsigned: consumers must recompute the two artifact hashes to detect a recomputed or
+substituted record. It is portable integrity metadata, not an authentication signature.
+
+If `generate-test` reports a conflict, it has left the existing output untouched. An identical
+artifact can be generated again safely; for different content, inspect the existing files and
+choose a fresh output directory (or remove them only after deciding they are no longer needed).
+
 ## What PhaseProbe adds—and what it does not
 
 | existing category | established strength | PhaseProbe’s narrower job |
@@ -269,6 +317,7 @@ python scripts/hygiene.py
 ```
 
 See [CONTRIBUTING.md](CONTRIBUTING.md) and the concrete good-first-issue templates in `.github/ISSUE_TEMPLATE/`.
+Report a reproducible defect with the [bug form](https://github.com/aliengineering-byte/phaseprobe/issues/new?template=bug_report.yml), or propose a bounded adapter or workflow with the [feature form](https://github.com/aliengineering-byte/phaseprobe/issues/new?template=feature_request.yml). Please do not include secrets or private model data.
 
 ## License and citation
 

{phaseprobe-0.2.0 → phaseprobe-0.3.0}/README.md

@@ -5,7 +5,7 @@
 Maintaining a simulation is risky when a tiny parameter or initial-condition change can cross a qualitative boundary while ordinary numeric assertions still look plausible. PhaseProbe runs a bounded, deterministic search, records exactly what it tested, and emits an offline report plus an executable pytest regression.
 
 ```console
-$ python -m pip install .
+$ pip install phaseprobe pytest
 $ phaseprobe scan --example logistic
 QUALITATIVE TRANSITION FOUND
 
@@ -24,15 +24,24 @@ $ python -m pytest -q tests/generated
 
 No API key, LLM, GPU, Docker, account, telemetry, network connection, or hosted service is required at runtime. PhaseProbe's base installation has no third-party runtime dependencies; NumPy and SciPy are isolated in the optional `scipy` extra.
 
+## Installation
+
+```bash
+pip install phaseprobe
+pip install "phaseprobe[scipy]"
+pip install pytest  # needed only to execute a generated regression test
+```
+
 ## Five-minute quick start
 
 Requires Python 3.10 or newer on Windows or Linux.
 
 ```bash
-python -m pip install .
+pip install phaseprobe pytest
 phaseprobe scan --example logistic
 phaseprobe replay .phaseprobe/runs/<run-id>/replay.json
 phaseprobe generate-test .phaseprobe/runs/<run-id>/replay.json
+phaseprobe verify-evidence tests/generated/logistic_map-pytest-evidence.json
 python -m pytest -q tests/generated
 phaseprobe report .phaseprobe/runs/<run-id>
 ```
@@ -52,22 +61,41 @@ Five-minute path:
 [![SciPy demo: solve_ivp evidence, tolerance replay, and generated pytest](assets/scipy-demo-static.png)](assets/scipy-demo.gif)
 
 The verified command transcript is [assets/scipy-demo-session.txt](assets/scipy-demo-session.txt),
-with a self-contained [HTML example report](examples/scipy/report.html).
+with a self-contained [HTML example report](examples/scipy/report.html). The following path starts
+from a clean environment and does not require a source checkout:
 
 ```bash
-python -m pip install "phaseprobe[scipy]"
-phaseprobe perturb --config examples/scipy/lorenz.json
-phaseprobe check --config examples/scipy/predator-prey.json
+python -m venv .venv
+# Linux: source .venv/bin/activate
+# Windows PowerShell: .venv\Scripts\Activate.ps1
+python -m pip install "phaseprobe[scipy]" "pytest==8.4.1"
+phaseprobe perturb --example scipy-lorenz
+phaseprobe check --example scipy-predator-prey
 phaseprobe replay .phaseprobe/runs/<run-id>/replay.json
 phaseprobe generate-test .phaseprobe/runs/<run-id>/replay.json
 python -m pytest -q tests/generated
 ```
 
+PhaseProbe 0.2.1 also recognizes the former Issue #4 command
+`phaseprobe perturb --config examples/scipy/lorenz.json` when that relative file is absent and
+loads the corresponding packaged example. This compatibility is limited to the four former
+`examples/scipy/` paths: an existing file always takes precedence, matching is case-sensitive,
+both slash styles are accepted, and unrelated missing paths remain errors. New documentation and
+automation should use the installed-safe `--example scipy-*` names.
+
 The Lorenz command searches a declared initial-`x` perturbation and reports only finite-time
-divergence evidence. `examples/scipy/lorenz-negative.json` is its short-window negative control.
-The predator–prey command checks the declared first integral with tightly resolved DOP853 settings;
-`examples/scipy/predator-prey-coarse.json` deliberately fails the same policy with loose RK23
-settings.
+divergence evidence and prints `FINITE-TIME TRAJECTORY DIVERGENCE FOUND`. Its installed
+short-window control is `--example scipy-lorenz-negative`. The predator–prey command checks the
+declared first integral with tightly resolved DOP853 settings and prints `CHECK POLICY PASSED`;
+`--example scipy-predator-prey-coarse` deliberately fails the same policy with loose RK23 settings.
+Each successful command writes a replay fixture and offline report below
+`.phaseprobe/runs/<run-id>/`.
+
+Run `phaseprobe perturb --help` or `phaseprobe check --help` to list installed example names. A
+missing packaged resource reports the PhaseProbe version and resource name. Adaptive SciPy replay
+compares the declared state, observable, invariant, endpoint, event, and retained-grid
+tolerances—it does not promise bitwise trajectory equality across platforms or dependency
+versions.
 
 For a direct Python API:
 
@@ -106,7 +134,8 @@ does not import it. See [the audited contract](docs/SCIPY_SOLVE_IVP_AUDIT.md),
 | `perturb` | Baseline/perturbed twin runs over bounded initial-state changes | Finding or no finding, exit `0` |
 | `check` | Execute a declared configuration policy for CI | Exit `1` only when policy fails |
 | `replay` | Validate fixture integrity and re-execute model, parameters, seed, initial state, tolerances, and retention | Declared `exact` or `tolerance` comparison passes |
-| `generate-test` | Validate and copy a fixture into a non-extensible pytest template | Executable test under `tests/generated/` |
+| `generate-test` | Validate and copy a fixture into a non-extensible pytest template without conflicting overwrites | Executable test under `tests/generated/` |
+| `verify-evidence` | Re-derive claims/replay decisions and validate bounded strict JSON, artifact hashes, paths, and the fixed template offline | Stable verified or invalid-input exit |
 | `report` | Regenerate terminal, versioned JSON, and self-contained offline HTML evidence | Local report files |
 
 Common options:
@@ -114,6 +143,7 @@ Common options:
 ```console
 phaseprobe scan --config examples/configs/logistic-scan.json
 phaseprobe perturb --example lorenz --json
+phaseprobe perturb --example scipy-lorenz --json
 phaseprobe check --example predator-prey
 phaseprobe scan --example logistic --fail-on-finding
 ```
@@ -128,6 +158,8 @@ Exit codes are stable: `0` completed, `1` declared policy or explicit `--fail-on
 | Lorenz system | `phaseprobe perturb --example lorenz` | Small initial separation exceeds the declared finite-time trajectory-distance threshold | Short window plus unreachable threshold reports no finding | [Lorenz, 1963](https://journals.ametsoc.org/view/journals/atsc/20/2/1520-0469_1963_020_0130_dnf_2_0_co_2.xml) |
 | Predator–prey | `phaseprobe check --example predator-prey` | Refined RK4 step preserves the analytic first integral within tolerance | Coarse step fails the invariant-drift policy | [Lotka, 1920](https://doi.org/10.1073/pnas.6.7.410) |
 | Genetic toggle | `phaseprobe perturb --example toggle` | Bounded initial-state perturbation reaches the opposite dominant state | Smaller declared range stays in the baseline basin | [Gardner, Cantor & Collins, 2000](https://www.nature.com/articles/35002131) |
+| SciPy Lorenz | `phaseprobe perturb --example scipy-lorenz` | DOP853 twin trajectories cross the declared finite-time distance threshold | `--example scipy-lorenz-negative` shortens the window | [Lorenz, 1963](https://journals.ametsoc.org/view/journals/atsc/20/2/1520-0469_1963_020_0130_dnf_2_0_co_2.xml) |
+| SciPy predator–prey | `phaseprobe check --example scipy-predator-prey` | Tight DOP853 settings preserve the declared first integral tolerance | `--example scipy-predator-prey-coarse` deliberately fails | [Lotka, 1920](https://doi.org/10.1073/pnas.6.7.410) |
 
 Each configuration records the seed, fixed integration/iteration settings, tolerances, burn-in, observation window, classification rule, refinement rule, invalid-state policy, and trace cap. See [examples/README.md](examples/README.md) for equations and interpretation.
 
@@ -150,6 +182,22 @@ manifest.json  sizes and SHA-256 hashes
 
 Model names used for generated test paths are sanitized. The generated source comes from a fixed template; configuration strings never become executable Python.
 
+`generate-test` validates the replay before writing anything. Alongside the fixed pytest template
+and copied fixture, it writes `<model>-pytest-evidence.json`: a path-portable claim/decision record
+containing repository/version attribution, the declared replay comparisons, SHA-256 hashes for
+both executable artifacts, the exact pytest command, and explicit scientific limitations.
+Run `phaseprobe verify-evidence <evidence.json>` before pytest to validate the strict schema,
+recompute the hashes, re-execute the replay policy, derive the claim/decision fields, and confirm
+that the regression still matches PhaseProbe's fixed template. Validation is offline, bounded to a
+1 MiB evidence document and 32 MiB per generated artifact, rejects duplicate keys and unsafe paths,
+and exits `2` for invalid input.
+The record is unsigned: consumers must recompute the two artifact hashes to detect a recomputed or
+substituted record. It is portable integrity metadata, not an authentication signature.
+
+If `generate-test` reports a conflict, it has left the existing output untouched. An identical
+artifact can be generated again safely; for different content, inspect the existing files and
+choose a fresh output directory (or remove them only after deciding they are no longer needed).
+
 ## What PhaseProbe adds—and what it does not
 
 | existing category | established strength | PhaseProbe’s narrower job |
@@ -231,6 +279,7 @@ python scripts/hygiene.py
 ```
 
 See [CONTRIBUTING.md](CONTRIBUTING.md) and the concrete good-first-issue templates in `.github/ISSUE_TEMPLATE/`.
+Report a reproducible defect with the [bug form](https://github.com/aliengineering-byte/phaseprobe/issues/new?template=bug_report.yml), or propose a bounded adapter or workflow with the [feature form](https://github.com/aliengineering-byte/phaseprobe/issues/new?template=feature_request.yml). Please do not include secrets or private model data.
 
 ## License and citation
 

{phaseprobe-0.2.0 → phaseprobe-0.3.0}/SCIENTIFIC_METHODS.md

@@ -19,6 +19,9 @@ Tolerance replay compares retained times/states, named numeric observables, clas
 invariant results and stored thresholds, endpoint/event evidence, and expected solver success.
 Environment and solver evidence are retained for interpretation. Artifact hashes still detect
 fixture tampering, but an adaptive trace hash is not required to match across supported platforms.
+The adapter validation suite checks an exponential system with an analytic terminal crossing in
+both forward and backward integration directions; this validates event plumbing, not exhaustive
+root detection between adaptive internal steps.
 See [the complete SciPy audit](docs/SCIPY_SOLVE_IVP_AUDIT.md).
 
 PhaseProbe 0.1.0 produces bounded computational evidence. It does not perform formal verification, model validation against observations, or computer-assisted proof.