docs(readme): sync status banner and roadmap to v0.2.0 (#27)

* docs(readme): update status banner and roadmap for v0.2.0

The status line and Status-and-roadmap section still referenced 0.1.0
after the v0.2.0 release shipped. Updates:

- Status banner now reads "0.2.0 - Phase 1 first wave shipped" and
  names the five additions (inspect, history, paraphrase, case study,
  CD pipeline).
- Roadmap section reframes 0.2.0 as the current release with all five
  items checked off; 0.1.0 stays as the historical Phase-0 MVP entry.
- "Coming next" section names the two locked tracks: diff sharpening
  (Phase D) and the post-Phase-D artifact infrastructure track
  (verify -> export --bundle -> embedded invocation). Lean by design;
  not pre-planning beyond Phase D.

* docs: sync release-state metadata for v0.2.0

Pre-merge audit caught several stale 0.1.0 references that should be
0.2.0 now that the release has shipped. All release-state metadata
(machine-readable + reader-facing):

- CITATION.cff: version 0.1.0 -> 0.2.0; date-released 2026-05-21 ->
  2026-05-22.
- CHANGELOG.md: add [0.2.0] reference link at the bottom (matches the
  existing [0.1.0] link pattern).
- docs/EVIDENCE.md: "Today (0.1.0)" -> "Today (0.2.0)" in the
  artifact-identity section; also names the post-Phase-D artifact
  track (verify -> export --bundle) since it's the concrete answer to
  what's "deferred" in that paragraph.
- docs/case-studies/01-invisible-character-substitution.md: pip
  install command updated from 0.1.0 to 0.2.0 so readers install the
  version that contains the case study itself.
- docs/RELEASE.md: example tag commands use v0.2.0 instead of v0.1.0;
  GitHub release section uses generic <version>/<thematic-name>
  placeholders; "next dev marker" section advances the example from
  0.2.0.dev0 to 0.3.0.dev0 and adds tests/unit/test_version.py to the
  bump checklist (caught by the actual 0.2.0 release).

Left alone (historically accurate):
- docs/case-studies/data/README.md "FalsifyAI version: 0.1.0" -
  provenance for when those Phase-0 campaign sessions were generated.
- docs/ARCHITECTURE.md "between 0.1.0 and 1.0" - resolver discipline
  statement, accurate from 0.1.0 baseline.
- CHANGELOG context lines mentioning "unchanged from 0.1.0" - accurate
  historical context within the 0.2.0 entry.

These commits will land in PR #27 (README sync to v0.2.0) since both
are pre-merge release-state metadata cleanup.

* docs(release): add release-state metadata audit checklist

Expands item 7 of the pre-release checklist into an explicit audit of
drift-prone version references, capturing the lesson from the v0.2.0
release where five files needed metadata syncs after the tag landed
(CITATION.cff, README status banner, EVIDENCE.md "Today (X.Y.Z)"
assertion, case study pip-install commands, CHANGELOG link).

Names the specific files that contain release-state metadata and must
advance on every release, AND distinguishes them from files that
contain historically-accurate version references that must NOT change
(provenance, "unchanged from 0.1.0" context, baseline discipline
statements).

Deliberately a human-judgment checklist, not a CI gate: a blanket grep
for version strings would produce both signals (release-state and
historical context) with no way to distinguish, and an automated rule
would erode trust faster than it saved time. The next release pays a
30-second deliberate check instead of a 30-minute audit.

Author: ericckzhou

CHANGELOG.md

@@ -287,4 +287,5 @@ All four are verified in CI via `tests/integration/test_examples.py`.
 - **`--latest-baseline` / `--latest-candidate`** flags on `diff` are not
   shipped; users pass explicit session ids. Phase 1 candidate.
 
+[0.2.0]: https://github.com/ericckzhou/falsifyai/releases/tag/v0.2.0
 [0.1.0]: https://github.com/ericckzhou/falsifyai/releases/tag/v0.1.0

CITATION.cff

@@ -26,5 +26,5 @@ keywords:
   - reliability-testing
   - AI-safety
 license: Apache-2.0
-version: 0.1.0
-date-released: '2026-05-21'
+version: 0.2.0
+date-released: '2026-05-22'

README.md

@@ -8,7 +8,7 @@ Most evaluation tools produce metrics. FalsifyAI produces **evidence** — durab
 [![Python](https://img.shields.io/badge/python-3.13%2B-blue)](https://www.python.org)
 [![License](https://img.shields.io/badge/license-Apache%202.0-green)](LICENSE)
 
-**Status:** 0.1.0 — Phase 0 MVP. Stable enough to use; spec language and verdict semantics are locked for the 0.1.x line.
+**Status:** 0.2.0 — Phase 1 first wave shipped (`inspect`, `history`, `paraphrase`, canonical case study, automated PyPI publishing). Spec language and verdict semantics remain locked for the 0.x line.
 
 ```bash
 pip install falsifyai
@@ -432,15 +432,20 @@ Contributions follow the conventions in [`CONTRIBUTING.md`](CONTRIBUTING.md). Ar
 
 ## Status and roadmap
 
-**0.1.0 (this release) — Phase 0 MVP.** Spec language, perturbation runtime, materializer, invariants, execution adapter, replay store, real verdict resolver (stratified bootstrap CI, CONSISTENTLY_WRONG, falsifiability scoring), and the three-command CLI (`run` + `replay` + `diff`).
+**0.2.0 (current release) — Phase 1 first wave.** Adds:
 
-**Phase 1 in progress** (selected by evidence from real-world validation runs, not roadmap completeness):
+- ✅ **`falsifyai inspect <session_id>`** — per-case deep-dive over preserved evidence. Surfaces every perturbed input, output, and invariant judgment. `--case <case_id>` expands one case; `--full` disables truncation. Pure consumer surface — the artifact already contained the data.
+- ✅ **`paraphrase` perturbation family** — LLM-generated semantic-preserving rewrites with embedding-similarity validity gating. Tests semantic robustness as an orthogonal pressure axis to the character-level families. Configurable per-spec (`count`, `similarity_threshold`, `max_attempts`, optional `model` override).
+- ✅ **`falsifyai history <case_id>`** — temporal view of one case across saved sessions. Newest-first, one row per session, showing verdict + CI + worst family per row. Reads `case.verdict` from preserved artifacts; no aggregation, no trend inference, no reinterpretation.
+- ✅ **Canonical case study** — [Invisible character substitution](docs/case-studies/01-invisible-character-substitution.md): cross-model `contains`-contract brittleness as the thesis (`history`), Pair 3 model-migration regression as the vivid concrete proof (`diff` + `inspect`), over a [bundled replay artifact](docs/case-studies/data/case-study-replays.db) you can re-open and reproduce verbatim.
+- ✅ **Automated PyPI publishing via Trusted Publisher (OIDC)** — `.github/workflows/publish.yml` fires on any `v*` tag push: verifies version match, re-runs tests, builds, validates, publishes. No long-lived tokens in repo.
 
-- ✅ **`falsifyai inspect <session_id>`** *(shipped)* — makes the replay artifact legible. Per-case deep-dive surfacing every perturbed input, every model output, every invariant judgment. `--case <case_id>` expands one case; `--full` disables truncation. Consumer-surface only; the artifact already contained the data.
-- ✅ **`paraphrase` perturbation family** *(shipped)* — LLM-generated semantic-preserving rewrites with embedding-similarity validity gating. Tests semantic robustness as an orthogonal pressure axis to the character-level families. Configurable per-spec (`count`, `similarity_threshold`, `max_attempts`, optional `model` override).
-- ✅ **`falsifyai history <case_id>`** *(shipped)* — temporal view of one case across saved sessions. Newest-first, one row per session, showing verdict + CI + worst family per row. Reads `case.verdict` from preserved artifacts; no aggregation, no trend inference, no reinterpretation.
-- ✅ **Canonical case study** *(shipped)* — [Invisible character substitution](docs/case-studies/01-invisible-character-substitution.md): the cross-model `contains`-contract brittleness pattern (`history`) plus the Pair 3 model migration regression (`diff` + `inspect`) over a [bundled replay artifact](docs/case-studies/data/case-study-replays.db) you can re-open and reproduce verbatim.
-- Hardened replay artifacts — cross-run lineage, immutable evidence semantics, and (eventually) signed bundles for cross-org transfer. These strengthen the existing artifact guarantees; the core differentiator remains the artifact's predictable semantics, not the wrapping.
+**0.1.0 — Phase 0 MVP.** Spec language, perturbation runtime, materializer, invariants, execution adapter, replay store, real verdict resolver (stratified bootstrap CI, CONSISTENTLY_WRONG, falsifiability scoring), and the three-command CLI (`run` + `replay` + `diff`).
+
+**Coming next** — selected by evidence, not theoretical completeness:
+
+- **`diff` sharpening** — `--strict`, `--show-trending`, exit code 6 for low-falsifiability gates. Tightens the binary regression criterion for users who want finer CI control without compromising resolver predictability.
+- **Artifact infrastructure track** — `falsifyai verify <session_id>` (integrity + provenance), `falsifyai export --bundle` (productize the case-study extraction pattern), and a persisted CLI-invocation field in `ReplayArtifact`. Locked sequence; reassess after a second case study or real user pressure.
 
 Each addition is evaluated against: *does this preserve evidence density, resolver predictability, and the discipline that makes the artifact trustworthy?* See [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md), [`docs/EVIDENCE.md`](docs/EVIDENCE.md), and [`CONTRIBUTING.md`](CONTRIBUTING.md) for the discipline.
 

docs/EVIDENCE.md

@@ -324,10 +324,14 @@ first place. A reliability claim with predictable semantics is the
 contract; cryptographic provenance strengthens portability of that
 contract.
 
-Today (0.1.0), the artifact has strong *deterministic* identity
+Today (0.2.0), the artifact has strong *deterministic* identity
 (sha256 hashes) but is not signed. The current artifact is suitable
-for use within a single trust boundary. This section will be revised
-when the Phase 1 work lands.
+for use within a single trust boundary. Cryptographic signing
+(Sigstore-style attestation) is deferred until artifacts need to
+cross trust boundaries; the post-Phase-D artifact track will ship
+`falsifyai verify` (integrity check + provenance display) and
+`falsifyai export --bundle` (productize the case-study extraction
+pattern) before signing is layered on.
 
 ---
 

docs/RELEASE.md

@@ -56,8 +56,42 @@ Run through every item before tagging. CI doesn't catch all of these.
    - `falsifyai/__init__.py` `__version__ = "..."`
    - `tests/unit/test_version.py` (update the hardcoded assertion)
 
-7. **README badges + status line current.** The status line at the top
-   should reflect the version being released.
+7. **Release-state metadata audit.** Several files contain a version
+   string that means *"the current release"* — they MUST advance on
+   every release. This is distinct from historical context references
+   (e.g. *"unchanged from 0.1.0"*) which MUST NOT change. A blanket
+   grep would produce both signals; the audit is a deliberate
+   human-judgment pass, not an automated gate.
+
+   Drift-prone files to check on every release:
+   - [ ] `README.md` status banner (top of file) — names the version
+     and the shipped feature wave for the public.
+   - [ ] `README.md` "Status and roadmap" section — `(current release)`
+     marker matches the new version; previous version stays as
+     historical entry.
+   - [ ] `CITATION.cff` — `version:` and `date-released:` fields
+     (machine-readable; consumed by citation tools).
+   - [ ] `docs/EVIDENCE.md` — the *"Today (X.Y.Z), the artifact has…"*
+     paragraph in §6.2; this is a release-state claim about current
+     guarantees.
+   - [ ] `docs/case-studies/*.md` — `pip install falsifyai==X.Y.Z`
+     commands in reproduction sections (so readers install the
+     version that contains the case study itself).
+   - [ ] `CHANGELOG.md` — new `[X.Y.Z]: <release URL>` link added
+     under the existing `[N-1.Y.Z]` reference at the bottom.
+   - [ ] `docs/RELEASE.md` (this file) — concrete example tag
+     commands and the "next dev marker" example should reference the
+     most recent release as their illustrative case.
+
+   Files that *also* contain version strings but are historically
+   accurate — do NOT change without specific reason:
+   - `CHANGELOG.md` body lines mentioning prior versions in context
+     (e.g. *"unchanged from 0.1.0"*).
+   - `docs/case-studies/data/README.md` provenance — the FalsifyAI
+     version recorded there reflects when the bundled artifacts were
+     *generated*, not the current release.
+   - `docs/ARCHITECTURE.md` discipline statements anchored to the
+     0.1.0 baseline.
 
 8. **Documentation links work.** Quick check that all
    `[link](docs/...)` references resolve on the branch you're tagging.
@@ -86,11 +120,11 @@ If `twine check` fails, the most common causes are:
 ## Tag (triggers automated publish)
 
 ```bash
-# Create an annotated tag matching the version.
-git tag -a v0.1.0 -m "Release 0.1.0"
+# Create an annotated tag matching the version (substitute the new version below).
+git tag -a v0.2.0 -m "Release 0.2.0"
 
 # Push the tag. This fires .github/workflows/publish.yml.
-git push origin v0.1.0
+git push origin v0.2.0
 ```
 
 The workflow:
@@ -150,8 +184,8 @@ falsifyai --help
 
 1. Go to the [Releases page](https://github.com/ericckzhou/falsifyai/releases).
 2. Click "Draft a new release."
-3. Choose the tag you just pushed (`v0.1.0`).
-4. Title: `0.1.0 — Phase 0 MVP` (or equivalent thematic name).
+3. Choose the tag you just pushed (e.g. `v0.2.0`).
+4. Title: `<version> — <thematic name>` (e.g. `0.2.0 — Phase 1 first wave`).
 5. Body: copy the matching section from `CHANGELOG.md` verbatim.
 6. Publish.
 
@@ -174,11 +208,13 @@ If the release warrants public attention:
    git push --force-with-lease origin dev
    ```
 
-2. **Bump version to next dev marker.** If this is the start of work
-   toward 0.2.0:
-   - `pyproject.toml`: `version = "0.2.0.dev0"`
-   - `falsifyai/__init__.py`: `__version__ = "0.2.0.dev0"`
-   - Open a PR titled `chore: bump version to 0.2.0.dev0`.
+2. **Bump version to next dev marker.** Optional but recommended when
+   starting work toward the next release. For example, after `0.2.0`
+   ships and the next planned release is `0.3.0`:
+   - `pyproject.toml`: `version = "0.3.0.dev0"`
+   - `falsifyai/__init__.py`: `__version__ = "0.3.0.dev0"`
+   - `tests/unit/test_version.py`: update the asserted version string.
+   - Open a PR titled `chore: bump version to <next>.dev0`.
 
 3. **Open a `CHANGELOG.md` "## [Unreleased]" section** under the version
    header for the next release's entries.

docs/case-studies/01-invisible-character-substitution.md

@@ -181,7 +181,7 @@ Every command shown above runs against the bundled SQLite. No model calls, no AP
 
 ```bash
 # 1. Install FalsifyAI
-pip install falsifyai==0.1.0
+pip install falsifyai==0.2.0
 
 # 2. Verify the bundle's integrity
 python -c "import hashlib; \
@@ -234,7 +234,7 @@ The U+202F substitution is memorable; the cross-model extraction brittleness is
 
 ## Reproduction checklist
 
-- [ ] `pip install falsifyai==0.1.0`
+- [ ] `pip install falsifyai==0.2.0`
 - [ ] Clone this repository or download [`case-study-replays.db`](data/case-study-replays.db) (SHA256 above)
 - [ ] Run each command in Section 6
 - [ ] Confirm that every output matches what is shown in this document