pytest-given 0.1.0__tar.gz → 0.3.0__tar.gz

{pytest_given-0.1.0 → pytest_given-0.3.0}/.gitignore

@@ -21,3 +21,11 @@ docs/superpowers/plans/
 .claude/settings.local.json
 .playwright-mcp/
 .mcp.json
+
+# Documentation site: build output and the copies docs_build stages into docs_dir
+/site/
+/docs/site/examples/
+/docs/site/assets/pytest-given-diagram-full.svg
+/docs/site/assets/fonts/source-sans-3-latin-wght-normal.woff2
+/docs/site/assets/fonts/source-code-pro-latin-wght-normal.woff2
+/docs/site/assets/logo.svg

pytest_given-0.3.0/AGENTS.md

@@ -0,0 +1,127 @@
+# Agents
+
+## Project overview
+
+See [README.md](README.md) for the pitch and quick start, and the [documentation site](https://nwilbert.github.io/pytest-given/latest/) (sources under `docs/site/`) for the public API and CLI flags. The rest of this document is contributor-facing.
+
+## Setup
+
+```bash
+uv sync --group dev
+```
+
+**All Python invocations go through `uv run`** — `uv run pytest …`, `uv run python -m …`, `uv run nox …`. There is no system `python` on PATH; bare `python` / `pytest` calls will fail. This applies to one-off commands (running a single test file, REPL exploration) too, not just nox sessions.
+
+**Never prepend `cd <path> &&` to commands.** The working directory is already set to the project root; the `cd` is redundant and triggers a permission prompt.
+
+## Quality gates
+
+`uv run nox` runs the default gate — `format`, `lint`, `mypy`, `test`, `coverage` (a 100% target), `audit` (a `pip-audit` of the locked dependencies). **Run it (or at minimum `uv run nox -s format lint mypy test`) before every commit.** The sessions below are on-demand; list them all with `uv run nox -l`.
+
+- `uv run nox -s examples` regenerates the JSON, HTML, and Markdown files under `examples/coffeeshop/`, `examples/hotel-booking/`, and `examples/file-glossary-booking/`. Run after changes to the renderer, templates, plugin output schema, or any example test file, and commit the updated outputs.
+- `uv run nox -s self_report` regenerates `examples/self-report/` — pytest-given applied to its own backend tests (see [Writing self-report scenarios](#writing-self-report-scenarios)). Run after decorating more tests or changing decorated ones, and commit the updated outputs.
+- **Only commit a regenerated report when its *content* actually changed.**
+  - Every regeneration rewrites `commit_sha` (to current HEAD, including the SHA-pinned source-link URLs), `timestamp`, and `duration_ms` in the JSON and HTML, so a report your change didn't really touch still shows a diff — `git checkout` those files rather than committing the noise.
+  - **Read the `.md` diff first**: the Markdown carries none of those fields, so it is the behavioral delta of your change in prose. An unchanged `.md` doesn't by itself prove the JSON/HTML are noise-only (glossary and story data never surface in the Markdown); a shifted source line does show up, in the `relpath:line::test_name` anchor under every heading.
+  - Regenerate only the reports a change can affect — `examples` narrates `examples/**`, `self_report` narrates `tests/**`. A shifted line number in a decorated backend test is therefore a real self-report change worth committing, even when no example changed.
+- Both regeneration sessions run the narration lint (`--given-lint`; see [Narration lint](docs/site/configuration/narration-lint.md) and the [design spec](docs/specs/2026-07-05-narration-lint-design.md)). `self_report` fails on any lint error — a real gate, keep the backend suite lint-clean. `examples` tolerates exit 1 for its intentional failures, which masks the lint exit code, so read the printed "narration lint" summary there. A step the lint mis-flags goes on the `given_lint_ignore` list (stale entries fail the run); the rule catalog and ignore mechanics are in the [authoring skill](src/pytest_given/.agents/skills/pytest-given-authoring/references/scenarios.md) under "Mechanical counterparts", and the honest-two-phase test an ignored `missing-phase` has to pass under "Phase structure".
+- `uv run nox -s benchmark` generates the large-scenarios suite and renders its JSON + HTML into `benchmarks/` (gitignored). Run it when a change could move report-generation cost; `benchmarks/bench.py` does size sweeps and cProfile runs directly.
+- `uv run nox -s build` builds the wheel + sdist and verifies them as a consumer would — `py.typed`, templates and bundled skills present, a real scenario run from a throwaway install, and [library-skills](https://library-skills.io) discovery of every bundled skill. The in-repo suite imports from `src/`, so this session is the only thing that catches a packaging regression. CI and the release workflow both run it.
+- `uv run nox -s docs_build` builds the documentation site under `site/` with `zensical build --strict`, after copying the four example reports, the full-size diagram and the report package's two upright fonts into gitignored spots under `docs/site/` (Zensical builds every file in `docs/site/` and cannot exclude any, so those copies are how single-sourced files get in; `CHANGELOG.md` instead reaches the site through a `pymdownx.snippets` include in `docs/site/changelog.md`, between its `site` markers, and the Home-page diagram is inlined the same way from `docs/site/assets/pytest-given-diagram.svg` so page CSS can theme it). The README shows the same diagram as `docs/pytest-given-diagram.svg`, a derived copy with the font embedded and the colour tokens resolved, which the Home page also links to as its full-size view: after editing the source SVG or its tokens, run `uv run nox -s diagram` and commit the result. Run it after changing anything under `docs/site/`; a broken cross-page link fails it. Preview with `uv run --group docs zensical serve` afterwards. The site self-hosts its fonts (`docs/site/assets/fonts/`, latin subsets from Fontsource, OFL notices in `LICENSES.txt` there; the upright faces are the report package's own under `src/pytest_given/report/templates/fonts/`, staged in by the build, only the italics live in the site tree) so a visitor's browser contacts no third party — keep `font = false` in `zensical.toml` and don't `@import` a font CDN; a new face gets its `.woff2` and copyright line added there. `docs_deploy` is the CI-only counterpart that publishes with mike — see [docs/releasing.md](docs/releasing.md#documentation-site).
+
+## Releasing
+
+Releases go to PyPI via a manually dispatched [Release workflow](.github/workflows/release.yml), authenticated with Trusted Publishing (no tokens anywhere) and always rehearsed on TestPyPI first. The step-by-step checklist, including the version bump and CHANGELOG section it needs, lives in [docs/releasing.md](docs/releasing.md).
+
+## Architecture
+
+`src/pytest_given/` is five library subpackages plus two entry points, with a
+strict dependency direction (convention, not lint-enforced):
+
+```
+model/                     the leaf — schema, serde, errors, shared text rules
+capture/  lint/  report/   each on model/ only, never on each other
+grouping/                  on model/ + capture/
+plugin/   cli/             the entry points; may import all five, and hold
+                           nothing the five could
+```
+
+What no filename tells you:
+
+- `grouping/` — the parametrize pass: a scenario's cases collapsed into one
+  narrated tree plus a parameter table, refusing the authoring forms that would
+  make that tree lie. Runs at session finish *before* the sinks are written, so
+  a bare `pytest` failing on one is the point, not a side effect.
+- `plugin/__init__.py` is the hook surface pluggy registers — the `pytest11`
+  entry point is the package, and pluggy scans a module's attributes for
+  `pytest_*` names, so the re-exports there *are* the registration.
+- `capture/` imports pytest nowhere, so all of it is unit-testable without a
+  session; a stray step warns with `model.PytestGivenWarning`, not pytest's.
+- `Glossary` exists twice on purpose: `model/schema.py` holds the storage the
+  report carries and serde rebuilds, and `capture/glossary.py` subclasses it
+  with the registration API, which needs a caller source location that the leaf
+  may not reach for. `pytest_given.Glossary` is the subclass; everything
+  internal annotates the base. `LookupGlossary` sits between them and owns the
+  `g['Guest']` read-back both user-facing glossaries share.
+- Each package exposes the *whole* job, not its parts: `report.emit_sinks`
+  (render → write → discard-on-failure, so a failure leaves no half-written
+  report) and `lint.run_lint`. Both entry points reach the sinks through
+  `emit_sinks`, which is what keeps `pytest-given report` behaving like the
+  plugin; the lint is the plugin's alone, since the CLI re-renders a report
+  rather than running a suite.
+
+`tests/` splits `unit/` (no pytest session needed) from `integration/`, which drives the plugin end to end through `pytester` inner runs (enabled by the root `conftest.py`). Narration written inside an inner run belongs to *that* run's collector — only the outer, decorated test reaches the self-report.
+
+The public API, including the step-text authoring forms (t-string vs `Template` vs plain string), is re-exported from `__init__.py` and documented in the skill's [references/api.md](src/pytest_given/.agents/skills/pytest-given-authoring/references/api.md).
+
+## Handling report output
+
+Outputs are opt-in; a bare `uv run pytest` writes nothing. The workflow for reading a run's narration (`--given-md`), querying the JSON report with `jq` by tag/term/status, re-rendering a saved run, and the bare-flag-order trap lives in the [navigating skill](src/pytest_given/.agents/skills/pytest-given-navigating/SKILL.md).
+
+## Report testing
+
+Any change to `report/templates/` (Jinja, CSS, `app.js`) or the `narration` filter in `html_renderer.py` **must** be Playwright-verified before commit. The project has no JS-side UI tests, and Python tests on rendered HTML cannot stand in: a substring match passes on a broken Alpine expression or a malformed `:class` binding. So:
+
+- **No Python tests that pin frontend markup** (class names, wrapper structure, inline-handler shape, SVG strings) — they check implementation, not behavior, and rot on every renderer refactor. Python tests stay on the renderer's data-shaped contract (which `data-param` value, which scenario IDs, which counts).
+- **No TDD for frontend changes**: apply the change, regenerate `examples/`, drive it in Playwright, capture the result.
+- Open e.g. `examples/coffeeshop/coffeeshop.html` (regenerate via `uv run nox -s examples`) with the Playwright MCP server, check `browser_console_messages` for errors after init, then drive the changed surface (hover, click, URL hash). Use `browser_snapshot` (not screenshots) to read page content and interact with elements.
+- Desktop only — assume a minimum viewport width of ~900px.
+- Traceback display and header metadata formatting are known limitations, not current priorities.
+- Never save Playwright screenshots into the project directory — use the session scratchpad or omit the `filename` parameter.
+
+**Setup and known traps** (`.mcp.json`, the `file://` page cache, browser installs) live in [docs/playwright-setup.md](docs/playwright-setup.md). `.mcp.json` is read at **session start**, so check that the `browser_*` tools exist before planning a task that ends in Playwright verification.
+
+## Writing self-report scenarios
+
+The narration rules live in the **`pytest-given-authoring` skill**, whose canonical source is [src/pytest_given/.agents/skills/](src/pytest_given/.agents/skills/pytest-given-authoring/SKILL.md) — every link in this document points there. The copy under `.claude/skills/` is a mirror: after editing the canonical copy, regenerate it with `uv run pytest-given skills install` and commit both (a sync test fails otherwise).
+
+**The skill is documentation with the same sync duty as the site** — downstream agents read it instead of the site, version-matched from the wheel. A change to the public API surface or its rules updates the site page under `docs/site/` *and* [references/api.md](src/pytest_given/.agents/skills/pytest-given-authoring/references/api.md); a change to narration/lint semantics updates [references/scenarios.md](src/pytest_given/.agents/skills/pytest-given-authoring/references/scenarios.md) and friends. No check catches prose drift between the site and the skill, so ask "does the skill need this too?" on every user-facing change; only the `python` blocks are covered — `tests/unit/test_skills_scripts.py` runs each against a report built from the model. The reviewing skill restates authoring rules as rubrics, so they share the same duty: its layer 2 mirrors `scenarios.md` ("Keeping it truthful", "Expected raises", "Vocabulary and tags"), and its layer 4 mirrors `glossaries.md` ("Keeping the glossary honest") and `stories.md` — change one, change both.
+
+Narration drifts like any other prose — the lint catches several ways step text and body can part company, not all of them — which is why [Quality gates](#quality-gates) has you read the regenerated `.md` rather than trust the text.
+Before merging changes to narrated tests, run the `pytest-given-reviewing` skill: it layers the lint, a semantic audit of step text against step bodies, and a hygiene pass over glossary, tags and stories.
+
+What is specific to this repo's self-report:
+
+- The glossary handle is `pg` — `GLOSSARY.md` loaded as a `FileGlossary` in `tests/conftest.py` via `tests/ubiquitous_language.py`. Term-rename mechanics live under [Conventions](#conventions); regeneration and lint gating under [Quality gates](#quality-gates).
+- **New or changed user-facing behavior needs a scenario, not just a test** — otherwise the behavior is invisible in the report. Decorate the test that best *states* the rule, one per rule, not per branch; the edge cases around it stay plain. Two gaps to check for: a rule the [CHANGELOG](CHANGELOG.md) announces that no scenario names, and a [GLOSSARY.md](GLOSSARY.md) row *asserting* behavior (`Templatize`, `Parameter table`) that no scenario demonstrates.
+
+## Conventions
+
+- Use the canonical vocabulary from [GLOSSARY.md](GLOSSARY.md) in prose as well as code — docs, skill references, and specs say the official term (`term ref`, not a paraphrase like "narrated term"). Naming and rename mechanics live in the skill's [references/glossaries.md](src/pytest_given/.agents/skills/pytest-given-authoring/references/glossaries.md); here, a rename lands in one commit (glossary row, `pg\[` references, implementation naming) plus a regenerated `uv run nox -s self_report`. Adding a term is safe, but still regenerate.
+- **Docstrings only for what the code cannot say** — a non-obvious invariant, a constraint that makes the shape necessary, a trap for the next reader — and a line or two at most. No signature restatement, no implementation narration, no `X is the only caller of Y` cross-references (they rot fastest; the reader can grep). Prefer a precise name to a sentence explaining a vague one. When you change a module, delete the sentences that have stopped being true rather than repairing them.
+- Avoid `Any` — use precise types, generics, `TYPE_CHECKING` imports, or `ContextVar[T]` over untyped `threading.local`.
+- Use `NewType` for domain-specific IDs (e.g., `NodeId`) and PEP 695 `type` statements for aliases. Avoid raw complex types like `dict[str, tuple[list[str], list[Any]]]` — introduce named types instead.
+- Only module-level imports — no inline/function-level imports.
+- **pytest config lives in `[tool.pytest]`** — native TOML mode since pytest 8.4/9.0, where lists are real arrays rather than newline-separated strings. `[tool.pytest.ini_options]` is the legacy INI-compat table; **never add it alongside** — pytest raises `UsageError` if both are present. New `addini` options take native types (a `type='linelist'` ini takes a TOML array).
+- Cross-platform: plugin and tests must pass on native Windows, macOS, Linux, and WSL (Linux interpreter over a `/mnt/<drive>` Windows checkout). Never hardcode a path separator or assume POSIX semantics — go through `pathlib`, `as_posix()` for stored/serialized paths, resolve before comparing. Path-form folding is confined to `capture/source.py` (mechanics in its docstrings; the why, and how to run one checkout from both Windows and WSL without the venvs colliding, in [docs/wsl-development.md](docs/wsl-development.md)). Only tests asserting WSL `/mnt`-absolute behavior may `skipif(sys.platform == 'win32', …)` — native-Windows pathlib reads `/mnt/<drive>` as drive-relative, not absolute — everything else passes on all four targets.
+- Relative imports inside the package throughout — `from .schema import Scenario` for siblings, `from ..model import Scenario` across subpackages (always through the subpackage root, never into its submodules). Tests use absolute imports and may reach into any internal path. The dependency direction those imports must respect is under [Architecture](#architecture).
+- Prefer `assert` over `# pragma: no cover` for invariant guards. Asserts document the invariant and fail loudly if violated; pragmas hide the line and silently bail. Reserve `# pragma: no cover` for code that genuinely cannot be exercised by a test (e.g. `if __name__ == '__main__':` script entry).
+- JSON reports written by older pytest-given versions are not supported: `pytest-given report` may drop or misread their fields. Don't add readers, migrations, or stale-shape errors for them.
+- Step-down rule: callers before callees, public before private. Read each file top-down from high-level API to implementation details.
+- TDD: write tests first (except frontend changes — see [Report testing](#report-testing)).
+- Commit messages: single line, no co-author trailers, no leading file/area labels like `TODO:` or `README:` — just describe the change ("note example cleanup as todo", not "TODO: note example cleanup"). Conventional-commit-style scope prefixes like `docs:` / `examples:` / `renderer:` are fine when they add information.
+- Keep commits coherent: each commit should represent one logical change. Don't split "do X", "tests for X", and "review-fixup for X" into separate commits — squash them before pushing. Don't bundle unrelated changes either.
+- **A user-facing change adds its `CHANGELOG.md` entry in the same commit**, under `## [Unreleased]`, in the fitting Keep a Changelog category (each category appears at most once per version — extend the existing heading rather than adding a second one). User-facing = public API, CLI flags, report output, lint rules, bundled skills; internal work (refactors, tests, CI, contributor docs) gets no entry.
+- **One sentence per entry**, written for someone upgrading: name the symbol, flag, or surface and say what changed — no rationale, measurements, or before/after detail. Only a breaking change earns more: the migration it needs. Visual and interaction polish gets one collective bullet per release ("the sidebar and its chips are visually tidied"), never a bullet per restyled element; accessibility fixes stay on their own line. When in doubt, the shorter entry is the right one.
+- Plan files under `docs/superpowers/plans/` are scratch artifacts — never commit them. Spec files under `docs/specs/` are committed.
+- New specs land under `docs/specs/proposed/`. When a spec's implementation lands, `git mv` it up one level into `docs/specs/` in the same commit, and fix its relative links in the same edit — a `../`-prefixed link to a sibling spec resolves into `docs/` once the file moves. `ls docs/specs/proposed` is the canonical list of outstanding design work.

pytest_given-0.3.0/CHANGELOG.md

@@ -0,0 +1,360 @@
+# Changelog
+
+All notable changes to this project are documented here.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+The release workflow reads the section matching the version in `pyproject.toml`
+and uses it as the GitHub Release body, so each version needs a heading of the
+form `## [x.y.z] - YYYY-MM-DD`.
+
+<!-- --8<-- [start:site] -->
+
+## [0.3.0] - 2026-09-27
+
+### Added
+
+- A documentation site at <https://nwilbert.github.io/pytest-given/> has a user guide, configuration and CLI reference, and the example reports. The bundled skills link to it, and the CLI help names the page on source-link templates.
+- The HTML report has a dark theme, with a Light / Dark / System control in its header that each browser remembers.
+- `--given-theme` / `given_theme` (and `--theme` on `pytest-given report`) set whether the HTML report opens light, dark, or following the viewer's system.
+- Tags can be organized hierarchically: a `/` in a tag nests it in the HTML report's Tags sidebar (`ticket/ABC-123` goes under a `ticket` heading), and selecting the heading filters to every tag beneath it.
+- Projects can also install the bundled skills with [library-skills](https://library-skills.io) (`uvx library-skills install --claude`), alongside the skills of their other dependencies.
+- One scenario can document a flow that spans several stories: `@scenario(stories=[a, b])` lists it under each story in the Stories tab, and the Scenarios view's sentence filter names the story when a report has several.
+- A sentence can be named (`sentence(..., name='checkout')`), so a pin can refer to it by name and survives reordering the story. The Stories timeline shows the name beside the sentence's coverage.
+
+### Changed
+
+- **Breaking.** Story vocabulary follows Domain Storytelling: a story is made of *sentences*, and *activity* is the verb kind. `activity()` is now `sentence()`, `path()` is now `clause()`, and `Glossary.verb()` is now `Glossary.activity()`. A file glossary's kind column says `activity` instead of `verb`, the report's `#activity-filter=` link parameter is now `#sentence-filter=`, and the HTML report says *Sentence* and *Activities* where it said *Activity* and *Verbs*.
+- **Breaking.** `@scenario(story=)` is now `stories=`.
+- **Breaking.** Pins refer to sentences by handle under `pins=` instead of by number: `given(..., activity=3)` becomes `given(..., pins=the_story[3])`, and `@scenario(activities=[2, 3])` becomes `pins=[the_story[2], the_story[3]]`. `activity_id=` is gone, because sentences are numbered by position; to pin a sentence independently of its position, name it and pin `the_story['name']`. A pin no longer requires the scenario to bind the pinned sentence's story.
+- **Breaking.** A scenario's `pins=` now sets its coverage outright: it covers exactly those sentences plus its steps' pins, with no narration matching. `activities=` only narrowed which sentences narration could cover. Pass `pins=[]` to a step or scenario to turn off narration matching without pinning anything.
+- The HTML report is restyled. It embeds Source Sans 3 and Source Code Pro, so it looks the same on every machine and offline. Lists share one surface instead of a card per row, Given/When/Then sit in a gutter beside the steps, and sidebar labels and counts use sentence case. Step narration and story sentences are set larger and darker than the surrounding labels and counts, at the same line spacing, so a scenario takes no more room.
+- The HTML report strips source comments from its inlined stylesheet and script, which saves about 29 KB per report and offsets part of the size the embedded fonts add.
+- Grouping errors for varying attachment labels and varying `str` narration name the parametrize case that differs. The varying-`str` error also suggests `group_parametrized=False` as a way out.
+- A story that no scenario covers now shows up in the report as uncovered, where before it was missing. The one exception is a story declared before the session started, such as one in a module still imported from an earlier `pytest.main()` in the same process: it is left out with a warning.
+- Story coverage ignores instances: a step narrating `guest`, or any guest instance, now covers a sentence naming `guest('Alice')`. Sentences that differ only by instance can be told apart only with a pin.
+- The authoring skill advises writing generic verbs (*searches for*, *adds*) as plain strings in sentences rather than glossary terms, keeping the glossary to domain vocabulary. The hotel-booking example follows it.
+- The authoring skill explains how coverage matching works (instances are ignored, and two sentences whose terms nest always cover together) and how to check coverage in the JSON report. The reviewing skill checks coverage from the report instead of re-deriving it.
+- The reviewing skill can list each scenario's narration beside its test's source for side-by-side review, and checks that a scenario demonstrates every rule the project's changelog announces. Both skills flag `match=` pins that use alternation, and a `when` that narrates setup while its body acts.
+- The authoring, reviewing and navigating skills cover sentence handles, `pins=` and `stories=`. The reviewing skill also checks that the test body exercises each sentence its scenario pins.
+
+### Fixed
+
+- When rendering a report fails unexpectedly, the previous run's report is still discarded instead of staying on disk looking current.
+- A `#scenario=` deep link now opens the right scenario when two node ids differ only in a character the slug folds, and no longer breaks the URL.
+- `pytest-given report` reports a non-UTF-8 input file as an error instead of crashing with a traceback.
+- An unknown `--given-source-link` preset is reported under the flag the user typed, not under the `given_source_link` ini name.
+- A refused scenario on a run with no `--given-*` sink no longer reports itself under a "report not written" heading.
+- `when_then(...)` rejects a `Template` narration in a test body, as `given`/`when`/`then` already do.
+- The Glossary view no longer lists a term's own name in another case (`guest.low`) under Instances.
+- On native Windows, stories and glossary terms now record where they are declared, so the lint rules that depend on it run there too.
+- `tag-shadows-term` now catches a tag that collides with a term id through a non-ASCII character that lowercases into ASCII.
+- A `dead-term` finding's message states the rule's actual criterion, including that a term ref in a `@scenario` name keeps a term alive.
+- The navigating skill shows the failure messages of a parametrized scenario's cases, where it printed an empty message. It also starts from a committed or CI-published report when one exists, instead of always rerunning the suite.
+- The reviewing skill lints the whole suite, where a selection failed on the project's ignore entries as stale, keeps the project's own `given_lint_rules` when enabling `dead-term`, and ranks findings in one explicit order.
+- A pin on an `Annotated` `given(...)` label now takes effect instead of being silently dropped, replacing the pins of the fixture step it relabels (`pins=[]` clears them). A pin on a step fixture's own `@given(...)` label also takes effect now.
+- A pin on a `@given` fixture scoped wider than `function` now counts in every scenario the fixture reaches, even when a test without `@scenario` set it up first. The run used to fail with a bare `AssertionError`.
+
+## [0.2.0] - 2026-09-04
+
+### Added
+
+- `pytest_given.PytestGivenWarning` is a top-level export, and a step or
+  `attach()` recorded in a test without `@scenario` now warns with it instead of
+  `pytest.PytestWarning`.
+- `--given-title=TEXT` (or the `given_title` ini) names the report, replacing the
+  rootdir name.
+- A parametrized scenario's parameter table now carries a typed column per varying
+  value — `param`, `derived`, or `attachment` for a varying attachment payload —
+  rather than one column per parametrize name.
+- `@scenario(group_parametrized=False)` declines the grouping and emits each case
+  as its own scenario, titled by its parametrize id.
+- The HTML report's sidebar gains **Terms** as a third browse axis, and all three
+  axes — Tags, Terms, Modules — now filter the Scenarios view the same way, with
+  each active filter carried in the URL.
+- The sidebar can be ordered by group size as well as by name, and resized by
+  dragging its seam or with the arrow keys.
+- A selected activity in the Stories view offers **Open in Scenarios**, filtering
+  the Scenarios view down to the scenarios covering it.
+
+### Changed
+
+#### CLI
+
+- **Breaking.** `--given-lint` is a plain boolean flag: write `--given-lint` and
+  `--no-given-lint` instead of `--given-lint=true` / `--given-lint=false`. Either
+  form still overrides the `given_lint` ini for one run.
+
+#### Authoring API
+
+- **Breaking.** Step narration must now be uniform across parametrize cases;
+  these fail the run with `PytestGivenError`, writing no report, instead of
+  quietly reporting case 1:
+
+  - a plain `str` (usually an f-string) that renders differently per case;
+  - a varying interpolation that is not a bare name (`t"{cup_size * 0.01}"`,
+    `t"{m.balance}"`);
+  - a t-string narrating a parametrize name that no longer holds the case's
+    value — either a local rebound it, or the body mutated it in place;
+  - a step whose set of `attach` labels differs between cases;
+  - a glossary term ref that names a different term or reads differently between
+    cases, including one bound to a parametrize column;
+  - passed cases that narrate different templates altogether.
+
+  Every one but the last is fixed by binding the varying part to a local and
+  narrating it with a t-string, keeping labels and term refs constant; varying
+  content belongs in the new `attachment` column. The last needs
+  `@scenario(..., group_parametrized=False)`, giving each case its own scenario.
+- **Breaking.** `attach()` now takes a plain `str` label; a t-string label raises
+  `PytestGivenError` — use an f-string.
+- **Breaking.** `attach()` called with no step open now raises `PytestGivenError`
+  instead of silently discarding the payload; move the call inside the step it
+  belongs to.
+- **Breaking.** `activity(..., id=N)` is now `activity(..., activity_id=N)`; the
+  `Activity.id` field itself is unchanged.
+- **Breaking.** `FileGlossary` is now a `Glossary` subclass rather than a wrapper
+  around one, so its `.glossary` attribute is gone — use the `FileGlossary`
+  itself wherever that attribute was passed.
+- A glossary term placed in an activity slot its declared kind forbids now raises
+  `PytestGivenError` when `activity(...)` is built rather than at session finish.
+- A glossary file whose table has a header and separator but no data rows now
+  says so, instead of reporting that no table was found.
+- A `FileGlossary` whose columns are all named now skips a Markdown table that
+  carries none of those names, so a glossary file may hold prose tables beside
+  the glossary; a table carrying some of them still raises, as does any table
+  under an index-based column spec.
+- `@scenario(activities=...)` now rejects a `str` and non-`int` members with a
+  `TypeError`.
+- `@scenario` now returns the test function itself rather than a wrapper, so the
+  test keeps its own signature.
+
+#### Plugin and run behavior
+
+- An unknown `given_source_link` preset is now a `UsageError` raised before the
+  suite runs.
+- The collection-time `@scenario` checks now report as a `UsageError` instead of
+  an `INTERNALERROR` traceback.
+- The narration lint summary prints each finding's location in its own column
+  rather than appended to the message.
+- `pytest-given` with no subcommand, and `pytest-given skills` with no
+  subcommand, now print that parser's usage and exit 2 instead of the root help
+  and exit 1.
+
+#### Report content (all formats)
+
+- **Breaking (JSON report).** `parameters.names` becomes `parameters.columns`
+  (`{id, name, kind}`), cells may hold an attachment object, placeholder parts
+  gain `column_id`, term-ref parts lose `param_column`, and a grouped step's
+  `narration.text` is the template rather than case 1's rendering.
+- **Breaking (JSON report).** A step no longer carries `status` or `error`;
+  failure lives on the scenario and on the parameter table's cases. A consumer
+  reading `step.status` should read `scenario.status` instead.
+- The Markdown report now shows a scenario's failure reason — the message and the
+  failing frame — under the scenario, and under the parameter table for each
+  failed case.
+
+#### HTML report
+
+- The browse sidebar leads with **Modules** and renders them as a collapsible
+  package tree whose nodes filter by path prefix; it no longer lists individual
+  scenarios under each group.
+- The report's colors are retuned into one system — a term ref in a step or a
+  scenario title reads as a word under a light wash rather than a bordered pill
+  (the Glossary view keeps its pills), and column colors are generated per
+  column — and the sidebar, its filter chips and the attachment badges are
+  tidied along with it.
+- The report opens and filters substantially faster on large suites, and its file
+  is smaller — a term reference now points at its glossary entry instead of
+  repeating the entry's definition, which takes about 18% off a term-heavy
+  report.
+- A glossary term referenced only in a `@scenario` title now contributes an
+  instance to the Glossary view, where it previously counted toward the term's
+  scenario tally while showing no instance.
+
+#### Bundled skills
+
+- The authoring and reviewing skills gain the report mechanics their rules depend
+  on, a symptom index, a completeness audit, the full lint rule catalog, and
+  guidance for sparser tagging.
+
+### Removed
+
+- **Breaking.** The `divergent-case-structure` lint rule; delete any
+  `given_lint_rules` or `given_lint_ignore` entry naming it, which would
+  otherwise fail config parsing.
+
+### Fixed
+
+#### Authoring API
+
+- Parametrize cases that claim different step activities now say so, instead of
+  reporting the more drastic "a different step structure".
+
+- A `@given` fixture scoped wider than `function` no longer loses its step when
+  the first test to use it has no `@scenario`.
+- `@given`/`@when`/`@then` are signature-preserving, so a decorated helper stays
+  callable to a type checker (was: `"StepDecorated" not callable`).
+- `@given(...)` above `@pytest.fixture` now raises and names the fix, instead of
+  surfacing as `fixture '<name>' not found`.
+- `@scenario(activities=...)` is now typed `int | Sequence[int] | None`, so a
+  bare `activities=2` type-checks.
+- `@scenario(activities=...)` with an unknown id, or without `story=`, is
+  rejected at the decorator rather than at collection.
+- A `-k`- or `--deselect`-narrowed run no longer fails on an authoring error in
+  a scenario it did not select.
+- Glossary term handles are now hashable, and equal for the same term whichever
+  accessor produced them.
+- A `when_then` step in a test without `@scenario` now points its warning at the
+  test rather than at pytest-given's own module.
+
+#### Narration lint
+
+- A `given_lint_ignore` entry beginning with a Windows drive letter
+  (`c:/repo/tests/t.py::test_x`) is no longer rejected as an unknown rule prefix.
+
+- A rule configured `off` no longer runs; levels were applied only after every
+  rule had already produced its findings.
+- A scenario tag with no ASCII alphanumerics (`tags=['日本語']`) no longer takes
+  the run down with a traceback from `tag-shadows-term`.
+
+#### Report
+
+- `pytest-given report` reports an unreadable input as an error instead of a
+  traceback (a directory raised `IsADirectoryError` through the console script).
+- A JSON report with an out-of-range scenario `status` or term `kind` is
+  rejected by name, instead of crashing a renderer with a bare `KeyError`.
+- A `<br>` inside an inline code span in a glossary definition renders as text
+  rather than as a line break.
+- The Terms browse axis no longer lists a term the selected glossary does not
+  hold.
+
+#### Plugin and run behavior
+
+- A `--given-json`/`--given-html`/`--given-md` path that could not be a report
+  file is now refused before the suite runs, instead of a bare flag swallowing a
+  following test path and overwriting — or, on a failed run, deleting — it.
+- `pytest-given report` now discards a stale report when the *render* fails, not
+  only when the write does.
+- `pytest-given report --source-link` is now validated on a `--format md` run
+  instead of being accepted and ignored, and an unknown preset is reported under
+  the name the user typed.
+- A `git` on PATH that cannot be executed no longer fails the run.
+- A nested in-process pytest run that dies while parsing its arguments no longer
+  strands the outer session's captured rootdir, which silently dropped every
+  later step's source anchor.
+- `@given`/`@when`/`@then` on an `async def` helper now records around the
+  awaited body, and async generator fixtures are handled too.
+- The narration lint now inspects `async def` step helpers, whose bodies were
+  invisible to every AST rule.
+- An explicit `--given-source-link=` now disables source links instead of falling
+  through to the `given_source_link` ini.
+- A finished scenario no longer leaves its collector — and every scenario and
+  step it recorded — reachable from a process-global for the rest of the process.
+- An error-level lint finding no longer overwrites a more specific exit code, so
+  an interrupted or nothing-collected run keeps reporting as one.
+- A report that cannot be written into an unwritable directory now reports
+  through the terminal summary instead of escaping as a bare traceback.
+- `pytest-given report` and `pytest-given skills install` now report a failed
+  write as a CLI error, and a failed `report` write discards the previous run's
+  report rather than leaving it to read as current.
+- `pytest-given report` now reports a bad input file — missing, unparsable, or
+  JSON that is not a pytest-given report — as a CLI error instead of a traceback,
+  as does an unknown `--source-link` preset.
+- A fixture that raises after its `yield` now fails the scenario it tore down,
+  instead of leaving it green in a report pytest counted as an error.
+- An error-level narration-lint finding now counts as an error in the run's
+  summary line.
+- Every failure building or writing a report — a suite reaching two glossaries, a
+  term used in incompatible slots, an unusable source-link template, an
+  unwritable output path — now surfaces as a terminal summary and a failing exit
+  code, where only grouping errors did.
+- The sinks are now rendered in full before any is written, and a failure on
+  either side discards all of them.
+
+#### Report content (all formats)
+
+- A parametrized scenario whose cases all skipped now keeps its skip reason
+  instead of reporting `skipped` with none.
+- A parameter row whose cell count disagreed with the table's columns silently
+  truncated in the HTML report; it now fails the same way it already did in
+  Markdown.
+
+- A parametrized scenario now keeps its place in source order instead of moving
+  below every unparametrized one.
+- A glossary term written as a code span keeps the markup inside it, so
+  `` `a*b*c` `` canonicalizes to `a*b*c`.
+- A parameter-table cell now reads the way the step pointing at it read, carrying
+  the interpolation's own format spec and, under `indirect=True`, the bound test
+  argument.
+- A `Template` narration's `text` is now what its parts render, so the report's
+  search box and `jq` queries match what the page displays.
+- The grouped step tree now comes from the first case that *passed*, where a
+  skipped case 1 used to render an empty tree.
+- A parametrize value that is a glossary term instance now narrates as its
+  display rather than the whole `Glossary` dataclass repr — in a step's
+  `Template` slot, in a scenario name, and in an
+  `Annotated[..., given(Template(...))]` parameter label.
+
+#### HTML report
+
+- Two test files sharing a basename across directories no longer abort the HTML
+  report; the scenarios' `#scenario=` slugs gain directory components instead.
+- A `#view=stories`, `#view=glossary` or `#term=` link opened against a report
+  that has no such tab now falls back to the Scenarios view.
+- The Glossary view's kind headings and their term counts now follow the search
+  and definition filters, and a filter matching nothing says so.
+- Content reaching past a scenario card's right edge is no longer clipped: a wide
+  parameter table and an attachment payload scroll, a source path and a
+  traceback's frame location wrap, and the source link no longer overlaps the
+  card's last element.
+- Jumping to a scenario from a story activity, or to a term's scenarios from the
+  Glossary tab, now clears filters that would hide the target; the filters in a
+  `#scenario=` deep link still win.
+- Accent-colored text and the parametrize column colors now meet WCAG AA, and
+  term kinds stay distinguishable for red-green color blindness.
+- The report is operable from the keyboard: status pills, browse-axis and
+  browse-tree rows, tag pills, story sidebar entries, activity and attachment
+  badges, and every expand/collapse chevron are now real buttons, and the view
+  tabs report which one is selected.
+- A step pinned with `given(..., activity=N)` now covers an activity regardless
+  of its term count; an under-anchored activity previously still rendered as
+  "not coverage-tracked".
+
+#### Bundled skills
+
+- The bundled skills are corrected against the shipped behavior.
+
+## [0.1.0] - 2026-08-08
+
+First public release.
+
+### Added
+
+- `@scenario` decorator plus `given` / `when` / `then` step blocks, usable as
+  both context managers and decorators, including on fixtures.
+- Self-contained interactive HTML report (`--given-html`), Markdown report
+  (`--given-md`), and JSON report (`--given-json`). The HTML bundles Alpine.js
+  and needs no server or external assets.
+- Structured step text: plain strings, `Template` objects, and t-strings
+  ([PEP 750](https://peps.python.org/pep-0750/)), with parameter interpolation
+  rendered as highlighted values.
+- `attach()` for text and JSON attachments on a step.
+- Domain Storytelling support: ubiquitous-language glossaries (inline or
+  Markdown-backed via `FileGlossary`), Domain Stories, and story coverage.
+- Narration lint (`--given-lint`) with a configurable rule catalog via
+  `given_lint_rules` and `given_lint_ignore`.
+- `--given-source-link` with `vscode`, `cursor`, `zed`, `pycharm`, and `github`
+  presets for jumping from a report step to its source.
+- `pytest-given` console script: `report` to re-render a saved JSON report, and
+  `skills install` to mirror the bundled agent skills into a project's
+  `.claude/skills/`.
+- Bundled authoring, navigating, and reviewing skills for AI agents, shipped in
+  the wheel and version-matched to the plugin.
+
+[Unreleased]: https://github.com/nwilbert/pytest-given/compare/v0.3.0...HEAD
+[0.3.0]: https://github.com/nwilbert/pytest-given/compare/v0.2.0...v0.3.0
+[0.2.0]: https://github.com/nwilbert/pytest-given/compare/v0.1.0...v0.2.0
+[0.1.0]: https://github.com/nwilbert/pytest-given/releases/tag/v0.1.0
+
+<!-- --8<-- [end:site] -->