Build PhaseProbe v0.1.0

.gitattributes

@@ -0,0 +1,5 @@
+* text=auto eol=lf
+
+*.gif binary
+*.jpg binary
+*.png binary

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,35 @@
+name: Bug report
+description: Report a reproducible PhaseProbe defect.
+title: "[Bug]: "
+labels: ["bug"]
+body:
+  - type: textarea
+    attributes:
+      label: Result first
+      description: What happened, and what should have happened?
+    validations:
+      required: true
+  - type: textarea
+    attributes:
+      label: Minimal reproduction
+      description: Include the command and a minimal non-sensitive configuration.
+    validations:
+      required: true
+  - type: input
+    attributes:
+      label: PhaseProbe and Python versions
+      placeholder: "phaseprobe 0.1.0; Python 3.12.13"
+    validations:
+      required: true
+  - type: dropdown
+    attributes:
+      label: Operating system
+      options: [Windows, Linux, Other]
+    validations:
+      required: true
+  - type: checkboxes
+    attributes:
+      label: Safety
+      options:
+        - label: I removed credentials, private model data, and personal information.
+          required: true

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Private security report
+    url: https://github.com/aliengineering-byte/phaseprobe/security/advisories/new
+    about: Report vulnerabilities without exposing exploit details publicly.

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,23 @@
+name: Feature request
+description: Propose a focused simulation-testing improvement.
+title: "[Feature]: "
+labels: ["enhancement"]
+body:
+  - type: textarea
+    attributes:
+      label: Testing job
+      description: Which transition, replay, evidence, or regression-testing job is missing?
+    validations:
+      required: true
+  - type: textarea
+    attributes:
+      label: Proposed evidence
+      description: Describe positive cases, negative controls, scientific terminology, and validation.
+    validations:
+      required: true
+  - type: textarea
+    attributes:
+      label: Alternatives and prior art
+      description: Link relevant tools or primary papers and explain the remaining gap.
+    validations:
+      required: true

.github/ISSUE_TEMPLATE/good_first_accessibility.yml

@@ -0,0 +1,17 @@
+name: "Good first issue: report accessibility"
+description: Improve keyboard, contrast, and semantic HTML evidence without external assets.
+title: "[Good first issue] Improve offline report accessibility"
+labels: ["good first issue", "documentation"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Audit the self-contained HTML report for semantic headings, table captions, contrast, print layout, and screen-reader labels. Add tests and before/after screenshots. Keep the report script-free, offline, and free of CDN resources.
+  - type: checkboxes
+    attributes:
+      label: Contributor checklist
+      options:
+        - label: I will document the audit method and measured changes.
+          required: true
+        - label: I will preserve HTML escaping and offline operation.
+          required: true

.github/ISSUE_TEMPLATE/good_first_pendulum.yml

@@ -0,0 +1,17 @@
+name: "Good first issue: damped pendulum adapter"
+description: Add a small deterministic adapter with positive/negative controls.
+title: "[Good first issue] Add a damped-pendulum adapter"
+labels: ["good first issue", "example"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Implement a typed damped-pendulum adapter, an energy-decay invariant, a positive transition/check, a negative control, a primary citation, deterministic tests, replay coverage, and documentation. Do not label numerical damping as physical evidence without a solver-refinement comparison.
+  - type: checkboxes
+    attributes:
+      label: Contributor checklist
+      options:
+        - label: I will add configuration, tolerances, invalid-state policy, and bounded trace retention.
+          required: true
+        - label: I will add positive, negative-control, replay, and generated-test coverage.
+          required: true

.github/ISSUE_TEMPLATE/good_first_schema.yml

@@ -0,0 +1,17 @@
+name: "Good first issue: JSON Schema fixtures"
+description: Publish schema documents and compatibility fixtures for config/replay/report JSON.
+title: "[Good first issue] Add JSON Schema validation fixtures"
+labels: ["good first issue", "tooling"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Add repository-owned JSON Schema documents for configuration, replay, and report version 1.0. Include valid and invalid fixtures, cross-platform tests, migration notes, and no new runtime dependency.
+  - type: checkboxes
+    attributes:
+      label: Contributor checklist
+      options:
+        - label: I will preserve existing version and integrity semantics.
+          required: true
+        - label: I will add actionable failure diagnostics and tests.
+          required: true

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,23 @@
+## Outcome
+
+Describe the user-visible testing outcome first.
+
+## Scientific interpretation
+
+- What does the evidence establish?
+- What does it not establish?
+- Which primary sources support model or algorithm claims?
+
+## Validation
+
+- [ ] `python -m ruff format --check .`
+- [ ] `python -m ruff check .`
+- [ ] `python -m mypy src tests`
+- [ ] `python -m pytest --cov=phaseprobe`
+- [ ] Positive case and negative control
+- [ ] Replay and generated pytest execution
+- [ ] Package build and clean packed-install smoke
+- [ ] `python scripts/check_links.py`
+- [ ] `python scripts/hygiene.py`
+
+List exact commands and measured results. Do not include private paths, credentials, PDFs, or fabricated evidence.

.github/workflows/ci.yml

@@ -0,0 +1,56 @@
+name: CI
+
+on:
+  push:
+    branches: [main, "release/**"]
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  quality-and-tests:
+    name: ${{ matrix.os }} / Python ${{ matrix.python }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+        python: ["3.10", "3.12", "3.14"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+          cache: pip
+      - run: python -m pip install --upgrade pip
+      - run: python -m pip install -e ".[dev]"
+      - run: python -m ruff format --check .
+      - run: python -m ruff check .
+      - run: python -m mypy src tests
+      - run: python -m pytest --cov=phaseprobe --cov-report=term
+      - run: python -m phaseprobe --version
+      - run: python -m phaseprobe scan --example logistic-negative
+
+  package-and-hygiene:
+    runs-on: ubuntu-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
+      - run: python -m build
+      - run: python -m venv .packed-smoke
+      - run: .packed-smoke/bin/python -m pip install dist/*.whl
+      - run: .packed-smoke/bin/python -m phaseprobe --version
+      - run: .packed-smoke/bin/python -m phaseprobe scan --example logistic-negative
+      - run: python scripts/check_links.py
+      - run: python scripts/hygiene.py
+      - uses: actions/upload-artifact@v4
+        with:
+          name: phaseprobe-packages
+          path: dist/*
+          if-no-files-found: error

.github/workflows/release.yml

@@ -0,0 +1,30 @@
+name: Tagged release validation
+
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: read
+
+jobs:
+  validate-tagged-package:
+    runs-on: ubuntu-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
+      - run: python -m build
+      - run: python -m venv .tag-smoke
+      - run: .tag-smoke/bin/python -m pip install dist/*.whl
+      - run: .tag-smoke/bin/python -m phaseprobe --version
+      - run: .tag-smoke/bin/python -m phaseprobe scan --example logistic
+      - run: python scripts/hygiene.py
+      - uses: actions/upload-artifact@v4
+        with:
+          name: phaseprobe-${{ github.ref_name }}
+          path: dist/*
+          if-no-files-found: error

.gitignore

@@ -0,0 +1,15 @@
+.research_private/
+.venv/
+.tools/
+.cache/
+.phaseprobe/
+dist/
+build/
+*.egg-info/
+__pycache__/
+*.pyc
+.coverage
+htmlcov/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/

AGENTS.md

@@ -0,0 +1,11 @@
+# PhaseProbe contributor instructions
+
+- Work exclusively inside the PhaseProbe repository root; never inspect or modify neighboring projects or workspaces.
+- Use the public author identity `Ali` only: no surname, personal email, workstation paths, credentials, or provider configuration in tracked files.
+- Keep scientific language precise: distinguish finite-time trajectory divergence, sensitive dependence, numerical instability, invariant violation, qualitative regime change, bifurcation evidence, stochastic variation, invalid integration, and solver failure. Never claim exact or formal results beyond the implemented evidence.
+- Support Windows and Linux on Python 3.10+ with no runtime LLM, API key, GPU, Docker, account, telemetry, or hosted service.
+- Keep copyrighted books, PDFs, extracted text, research notes, caches, environments, tools, build output, and run output out of Git.
+- Required validation: `python -m ruff format --check .`, `python -m ruff check .`, `python -m mypy src tests`, `python -m pytest`, `python -m build`, packed-install smoke test, quick start, examples, replay, generated-test execution, privacy/secret/large-file scans, and clean Git status.
+- Do not fabricate tests, performance, scientific evidence, benchmark results, users, or adoption claims.
+- Do not publish to PyPI without separate authorization.
+- Release only after all local gates pass; then use the authenticated `aliengineering-byte` GitHub account, pass CI, tag an annotated `v0.1.0`, create the release, and verify a fresh unauthenticated clone.

ARCHITECTURE.md

@@ -0,0 +1,55 @@
+# Architecture
+
+PhaseProbe separates simulation semantics from search, evidence, and test materialization.
+
+```text
+JSON config / built-in example
+            |
+            v
+       typed adapter ----> deterministic step + observe
+            |                         |
+            v                         v
+ bounded engine ----> finite validation ----> capped trace + SHA-256
+      |     |
+      |     +---- scan / perturb / check policy
+      v
+ outcome ----> run artifacts ----> replay verification ----> fixed pytest template
+      |
+      +---- terminal / JSON / self-contained HTML
+```
+
+## Modules
+
+- `config.py` validates schema `1.0`, loads packaged examples, and emits canonical JSON.
+- `types.py` defines the public adapter protocol, state shape, trace point, and invariant result.
+- `models/` contains four independent reference adapters. They are examples, not engine special cases.
+- `engine.py` owns bounded execution, NaN/Inf/hard-limit checks, trace retention, scanning, perturbation, bracket refinement, repeatability confirmation, and CI policy evaluation.
+- `artifacts.py` creates one finite run directory and hashes each evidence file.
+- `replay.py` verifies fixture integrity before re-executing exact model/config/seed/state/parameter inputs and comparing classifications plus retained trace hashes.
+- `generate.py` uses a fixed code template and sanitized names. It never evaluates configuration text.
+- `reporting.py` renders terminal, JSON, and offline HTML with explicit limitations.
+- `cli.py` maps the six public commands to stable exit codes.
+
+## Adapter design
+
+The engine deliberately does not require NumPy. A state is a tuple of finite floats; this keeps serialization and perturbation explicit. Downstream adapters may wrap larger simulators, but their `step` boundary must return a bounded tuple suitable for deterministic replay. Observations are scalar mappings and cannot carry arbitrary executable objects.
+
+An adapter supplies scientific judgment: initial conditions, state advance, observables, qualitative classification, and invariants. The engine supplies operational judgment: search bounds, retention, failure containment, hashes, artifacts, and policy exits.
+
+## Determinism boundary
+
+PhaseProbe controls seeds, canonical configuration serialization, fixed command order, search grids, state perturbations, trace retention, and fixture hashing. An external adapter remains responsible for deterministic solver settings, thread behavior, native library versions, and hardware-sensitive arithmetic. Exact replay hashes intentionally expose drift; users may choose a classification-only policy in a future version, but v0.1.0 replay is strict.
+
+## Artifact safety
+
+Trace points are capped per series. Run IDs combine UTC time and an evidence digest. Replay fixtures carry a schema version and SHA-256 over every unsigned field. Generated tests copy a validated fixture into `tests/generated/fixtures/` and contain only a sanitized identifier plus a fixed relative path.
+
+## Extension checklist
+
+1. Give the adapter a stable `identity` version.
+2. Make `initial_state` deterministic for the declared seed.
+3. Return the same state dimension after every step.
+4. Define classifier thresholds in configuration tolerances.
+5. Distinguish mathematical invariants from diagnostic bounds in invariant details.
+6. Add positive, negative-control, invalid-state, repeatability, and replay tests.
+7. Cite a primary technical source for the model and document solver limitations.

CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+
+All notable changes are documented here. PhaseProbe follows semantic versioning.
+
+## 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.

CITATION.cff

@@ -0,0 +1,17 @@
+cff-version: 1.2.0
+message: "If you use PhaseProbe, cite the software release."
+title: "PhaseProbe"
+type: software
+authors:
+  - name: "Ali"
+version: 0.1.0
+date-released: 2026-08-01
+url: "https://github.com/aliengineering-byte/phaseprobe"
+repository-code: "https://github.com/aliengineering-byte/phaseprobe"
+license: Apache-2.0
+abstract: "PhaseProbe finds bounded qualitative simulation transitions and turns reproducible evidence into replay fixtures and pytest regressions."
+keywords:
+  - simulation testing
+  - reproducibility
+  - dynamical systems
+  - regression testing

CODE_OF_CONDUCT.md

@@ -0,0 +1,9 @@
+# Code of conduct
+
+PhaseProbe contributors must make technical collaboration safe, respectful, and evidence-led.
+
+Welcome people regardless of background or identity. Discuss ideas and code rather than personal characteristics. Give reproducible evidence, acknowledge uncertainty, accept correction, and avoid harassment, threats, sexualized conduct, discrimination, doxxing, or sustained disruption.
+
+Maintainers may edit or remove contributions and restrict participation when behavior harms the community. Report conduct concerns privately through the repository’s security/contact path; do not include sensitive personal information in a public issue. Reports will be reviewed fairly and with as much confidentiality as practical.
+
+Good-faith disagreement about scientific methods is welcome. Fabricated evidence, misrepresentation of certainty, or retaliation against someone raising a reproducibility concern is not.

CONTRIBUTING.md

@@ -0,0 +1,36 @@
+# Contributing
+
+Contributions are welcome when they preserve PhaseProbe’s narrow testing job and scientific language.
+
+## Setup
+
+```bash
+python -m venv .venv
+# Windows: .venv\Scripts\python -m pip install -e ".[dev]"
+# Linux:   .venv/bin/python -m pip install -e ".[dev]"
+python -m ruff format --check .
+python -m ruff check .
+python -m mypy src tests
+python -m pytest --cov=phaseprobe
+```
+
+Before a pull request, also run `python -m build`, install the wheel into a clean environment, execute the logistic quick start, run `python scripts/check_links.py`, and run `python scripts/hygiene.py`.
+
+## Scientific changes
+
+New adapters or classifiers must include:
+
+- equation or model definition and a primary technical citation;
+- deterministic positive case and negative control;
+- seed, solver/iteration settings, tolerances, burn-in, observation window, and invalid-state policy;
+- an explanation of what the classifier establishes and what it does not;
+- replay and generated-test coverage;
+- solver-refinement or convergence evidence where numerical integration matters.
+
+Do not call finite-time divergence a Lyapunov exponent, a numerical bracket an exact bifurcation point, or a bounded search result globally minimal.
+
+## Pull requests
+
+Keep changes focused, update documentation and `CHANGELOG.md`, and report exact validation commands. Never add copyrighted books, PDFs, extracted private text, credentials, personal email addresses, telemetry, runtime API/LLM/GPU/Docker requirements, or unsupported performance/adoption claims.
+
+At least three starter tasks are available as structured good-first-issue templates: add a damped-pendulum adapter, add JSON Schema validation fixtures, and improve HTML-report accessibility.