Add trunk-based CI/release pipeline + tag-driven versioning (#23)

* seeds: sync 2026-06-23

* Add Context environment + telemetry to the DIZZY generator

Two optional top-level feat sections supply extra inputs to a function's
context, declared once and referenced by name from procedures, policies,
projections, and queriers:

- environment: injected constants/variables (in place of os env), surfaced
  as context.env.<name>; shapes authored in def/environment.yaml.
- telemetry: host-injected observation sinks (the emitters pattern, but for
  transport-only observation, never recorded as events), surfaced as
  context.telemetry.<name>(payload); shapes in def/telemetry.yaml.

Folded into the existing pipeline: generate definitions scaffolds the two
def files; generate static compiles them to gen_def/pydantic/{environment,
telemetry}.py and threads optional env/telemetry fields into each function
context via the shared generators/context_extras helper. No-op (byte-
identical) when a function declares neither.

Includes a new agent.feat.yaml fixture exercising all four function kinds,
scaffold + context snapshots, loader normalization/validation, and CLI e2e.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* Fix scaffold generators emitting invalid YAML for multi-line descriptions

commands/events/models/queries rendered `description: {text}` inline, so a
multi-line `|` block from the feat file produced unindented continuation
lines — invalid YAML that broke `generate static`. Route them all through
generators/yaml_util.description_lines, which emits a literal block scalar
when the description spans multiple lines (single-line output unchanged).

Closes dizzy-bb64.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* seeds: sync 2026-06-23

* working agent demo

* examples/agent: streaming agent demo + slim to reactivity loop

Build out the agent example as a runnable demo of the environment + telemetry
context inputs, then slim it to a focused single-turn shape:

- environment `llm` (model / api_key / base_url) injected in place of os.environ
- two telemetry sinks: `stream_chunk` (per-token text delta, live) and `usage`
  (turn-level token counts, reported once) — kept separate because usage is a
  completion-time aggregate, not available per chunk
- run_agent_turn implementation streams via the injected client, forwarding
  deltas to stream_chunk and reporting usage, then emits the durable events
- demo.py is the host: in-memory event log, emit closures, injected llm config,
  and the two telemetry sinks; streams the reply to the CLI

Removes the read side (get_conversation query, conversations model, and both
projections) — unused by this single-turn demo, leaving a clean reactivity
loop: send_message -> run_agent_turn -> user_message_sent / agent_replied.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* Add trunk-based CI/release pipeline, tag-driven versioning, docs

- CI (`ci.yml`): pytest gates on PRs/main across py3.11-3.13; ruff lint/format
  and `ty` run as an advisory (non-required) `quality` job.
- Release (`release.yml`): a `v*` tag builds sdist+wheel and cuts a GitHub
  Release with the artifacts attached. No package-index publishing for now.
- Version is derived from git tags via hatch-vcs; `__init__` reads the
  build-time `_version.py` (gitignored) with an importlib fallback.
- pyproject: release metadata (license/authors/classifiers/urls), ruff config
  (generated files excluded, B008 ignored for the Typer idiom), ruff + ty dev deps.
- justfile: `lint`, `fmt`, `fmt-check`, `ci`, `build`, `examples-check` recipes.
- CHANGELOG.md (Keep a Changelog) + CONTRIBUTING.md (trunk-based flow, gates, release).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* Apply ruff lint + format cleanup

Mechanical `ruff check --fix` + `ruff format` across hand-authored source and
tests (generated schema files excluded), plus the few manual fixes ruff could
not auto-apply: wrap over-long error strings, add `stacklevel` to the adapter
warning, drop an unused test variable, and narrow a blind `Exception` to
`ValidationError`. ruff now passes clean; the remaining advisory signal is ~30
`ty` diagnostics, tracked separately.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* changelog: document core DIZZY capabilities for 0.1.0

The Unreleased section described only the CI/release infra. Add the actual
product surface (feature-file format, the generate pipeline, runtime targets,
simulate/onboard/docs/config, worked examples) ahead of the tooling items, so
the inaugural 0.1.0 changelog reflects what DIZZY does.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* seeds: sync 2026-06-25

---------

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

Author: ConradMearns

.github/workflows/ci.yml

@@ -0,0 +1,51 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  # The gate: tests must pass before merge. Mark this job (each matrix entry)
+  # as a required status check in branch protection.
+  test:
+    name: test (py${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          # hatch-vcs needs full history + tags to compute the version.
+          fetch-depth: 0
+      - uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+      - run: uv sync --python ${{ matrix.python-version }}
+      - run: uv run pytest
+
+  # Advisory: lint / format / type signal. NOT a required check, so it never
+  # blocks a merge while these are being adopted across the codebase.
+  quality:
+    name: quality (advisory)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+      - run: uv sync
+      - name: ruff lint
+        run: uv run ruff check dizzy/src/dizzy dizzy/tests
+      - name: ruff format check
+        run: uv run ruff format --check dizzy/src/dizzy dizzy/tests
+      - name: ty type check
+        run: uv run ty check dizzy/src/dizzy dizzy/tests

.github/workflows/release.yml

@@ -0,0 +1,38 @@
+name: Release
+
+# Trunk-based: a release is just a version tag pushed to main.
+#   git tag v0.2.0 && git push origin v0.2.0
+#
+# This builds the sdist + wheel and attaches them to a GitHub Release.
+# (Publishing to a package index is intentionally out of scope for now.)
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  release:
+    name: build + GitHub Release
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: astral-sh/setup-uv@v5
+      - name: Verify tag matches package version
+        run: |
+          uv sync
+          PKG="$(uv run python -c 'import dizzy; print(dizzy.__version__)')"
+          TAG="${GITHUB_REF_NAME#v}"
+          echo "tag=$TAG package=$PKG"
+          test "$PKG" = "$TAG" || { echo "::error::tag $TAG != package version $PKG"; exit 1; }
+      - run: rm -rf dist && uv build
+      - name: Create release
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          gh release create "$GITHUB_REF_NAME" dist/* \
+            --title "$GITHUB_REF_NAME" \
+            --notes "See [CHANGELOG.md](https://github.com/PNNL/dizzy/blob/main/CHANGELOG.md)."

.gitignore

@@ -3,6 +3,14 @@ __pycache__/
 .env
 .vscode
 
+# Build / publish artifacts
+dist/
+build/
+*.egg-info/
+
+# Generated at build time by hatch-vcs from the git tag
+dizzy/src/dizzy/_version.py
+
 # Generated lib/ workspace artifacts (regenerated by `uv sync`)
 .venv/
 examples/guestbook/lib/python-uv/uv.lock

.seeds/issues.jsonl

@@ -68,3 +68,13 @@
 {"id":"dizzy-ddb3","title":"dizzy drift: compare runtime traces to the feature-file; flag undeclared emissions/access/components","status":"open","type":"feature","priority":3,"createdAt":"2026-06-18T00:12:50.601Z","updatedAt":"2026-06-18T00:13:03.089Z","description":"v4. Requirements: docs/cli.md § dizzy drift. Compare runtime traces against the feature-file: undeclared event emissions, undeclared model access, components present in one but not the other. The feature-file as enforced contract, not documentation. Built in THIS repo.","labels":["roadmap"],"blockedBy":["dizzy-cb2f"]}
 {"id":"dizzy-bf28","title":"Align onboard/prime verbs with Seeds: rename dizzy onboard→prime, add onboard installer","status":"open","type":"task","priority":2,"createdAt":"2026-06-18T14:00:27.325Z","updatedAt":"2026-06-18T14:00:42.157Z","description":"## Problem\n`dizzy onboard` is misnamed. Comparing the three verbs:\n\n| Verb | Behavior | Mutates files? | Cadence |\n|------|----------|----------------|---------|\n| `sd onboard` | Writes/updates a Seeds section into CLAUDE.md/AGENTS.md (`--check`, `--stdout`) | YES — installer | Once per repo |\n| `sd prime` | Prints agent context (rules, command ref, workflow) to stdout | No | Every session / after compaction |\n| `dizzy onboard` | Prints an agent overview to stdout (components, feature-file role, change taxonomy, exemplars) | No | Read-first per session |\n\n`dizzy onboard` is read-only and per-session — its own doc (docs/onboard.md, docs/cli.md:94-101) even says \"Modeled on the seeds tool's `prime` verb.\" So it semantically IS `dizzy prime` wearing the wrong name. DIZZY currently has NO equivalent of `sd onboard` (the installer that injects a section into CLAUDE.md).\n\n## Recommendation — adopt the Seeds two-verb split\n1. Rename `dizzy onboard` → `dizzy prime` — the per-session context printer (it already is this).\n2. Reclaim `dizzy onboard` for the installer role it's missing: write a DIZZY section into CLAUDE.md/AGENTS.md (with `--check`/`--stdout`), like `sd onboard`.\n\nResult: same mental model agents already learn from Seeds — `onboard` = install once, `prime` = load each session.\n\n## Implementation notes / order (per CLAUDE.md conventions)\n- `onboard` is a SHIPPED command (docs/cli.md:25). Change scope in docs/cli.md FIRST, then seeds, then code.\n- Rename canonical doc dizzy/src/dizzy/docs/onboard.md → prime.md and update the `_print_doc(\"onboard.md\")` call (cli.py:398-401).\n- Keep a deprecation alias `onboard` → `prime` for a release for anything referencing the old name.\n- New `dizzy onboard` installer: write DIZZY section to CLAUDE.md/AGENTS.md, support `--check` and `--stdout`.\n\n## Minimal fallback\nIf renaming a shipped verb is too much churn now: just ADD `dizzy onboard` (installer) alongside the existing printer, and rename the printer to `prime` later. Downside: leaves the confusing semantics in place."}
 {"id":"dizzy-7609","title":"examples/recipes: chained PROV recipe workflow","status":"closed","type":"task","priority":2,"createdAt":"2026-06-18T14:38:47.244Z","updatedAt":"2026-06-18T14:51:24.894Z","closedAt":"2026-06-18T14:51:24.894Z"}
+{"id":"dizzy-d4b7","title":"Context Environment & Telemetry: inject constants and observation sinks into DIZZY function contexts","status":"open","type":"epic","priority":2,"createdAt":"2026-06-23T16:45:31.674Z","updatedAt":"2026-06-23T16:45:53.873Z","blocks":["dizzy-a701","dizzy-9745","dizzy-aa1d","dizzy-0983","dizzy-262a","dizzy-2686","dizzy-7e4e"]}
+{"id":"dizzy-a701","title":"feat schema + loader: environment/telemetry sections and per-function reference lists","status":"closed","type":"task","priority":2,"createdAt":"2026-06-23T16:45:52.821Z","updatedAt":"2026-06-23T16:47:36.103Z","description":"Add top-level environment/telemetry sections (EnvironmentDef/TelemetryDef, {name,description}) to def/feat.yaml; add environment/telemetry multivalued-string lists to Procedure/Policy/Projection/Querier(QueryDef). Regenerate feat_schema.py via just gen-feat-pydantic. Wire _SECTIONS normalization + cross-ref validation in feat_loader.py.","blockedBy":["dizzy-d4b7"],"blocks":["dizzy-9745","dizzy-aa1d"],"closedAt":"2026-06-23T16:47:36.103Z"}
+{"id":"dizzy-9745","title":"scaffold generators: def/environment.yaml + def/telemetry.yaml","status":"closed","type":"task","priority":2,"createdAt":"2026-06-23T16:45:52.895Z","updatedAt":"2026-06-23T16:48:49.927Z","description":"New generators/environment.py + generators/telemetry.py mirroring events.py: one LinkML class per entry, skip-if-exists. environment classes = injected constant shapes; telemetry classes = sink payload shapes.","blockedBy":["dizzy-d4b7"],"blocks":["dizzy-aa1d","dizzy-0983"],"closedAt":"2026-06-23T16:48:49.927Z"}
+{"id":"dizzy-aa1d","title":"context threading: env + telemetry fields into procedure/policy/projection/querier contexts","status":"closed","type":"task","priority":2,"createdAt":"2026-06-23T16:45:52.976Z","updatedAt":"2026-06-23T16:50:44.671Z","description":"Shared helper rendering <name>_env dataclass (fields typed by gen_def.pydantic.environment.<entry>) and <name>_telemetry dataclass (Callable[[Payload],None], emitters pattern, from gen_def.pydantic.telemetry.<entry>). Add optional env/telemetry fields to each context. Build+validate procedures first, then replicate to policies, projections, querier. No-op when lists empty.","blockedBy":["dizzy-d4b7"],"blocks":["dizzy-0983"],"closedAt":"2026-06-23T16:50:44.671Z"}
+{"id":"dizzy-0983","title":"CLI pipeline: fold env/telemetry scaffold + linkml compile into generate definitions/static","status":"closed","type":"task","priority":2,"createdAt":"2026-06-23T16:45:53.071Z","updatedAt":"2026-06-23T16:52:50.624Z","description":"def_cmd: write_scaffold_environment/telemetry when declared. gen(static): extend missing-stub guard, run_linkml_pydantic per entry into gen_def/pydantic/{environment,telemetry}/<name>.py.","blockedBy":["dizzy-d4b7"],"blocks":["dizzy-262a"],"closedAt":"2026-06-23T16:52:50.624Z"}
+{"id":"dizzy-262a","title":"tests: scaffold + context snapshots, loader validation, CLI e2e for env/telemetry","status":"closed","type":"task","priority":2,"createdAt":"2026-06-23T16:45:53.156Z","updatedAt":"2026-06-23T16:57:19.856Z","description":"Add env/telemetry to fixtures; new test_environment/test_telemetry; extend procedure/policy/projection/querier generator tests (with + without); loader normalization + negative cross-ref; CLI e2e asserts def/environment.yaml + def/telemetry.yaml written. just test + just check green.","blockedBy":["dizzy-d4b7"],"closedAt":"2026-06-23T16:57:19.856Z"}
+{"id":"dizzy-2686","title":"docs: authoring.md + SPECIFICATION.md for environment/telemetry (whitepaper deferred)","status":"closed","type":"task","priority":3,"createdAt":"2026-06-23T16:45:53.243Z","updatedAt":"2026-06-23T17:00:30.371Z","description":"Document the two top-level sections and per-function reference lists in authoring.md and SPECIFICATION.md. Whitepaper.typ prose deferred to a separate maintainer pass.","blockedBy":["dizzy-d4b7"],"closedAt":"2026-06-23T17:00:30.371Z"}
+{"id":"dizzy-7e4e","title":"follow-up: env/telemetry cross-runtime (rust-cargo, typescript-npm) in generate libraries","status":"open","type":"task","priority":3,"createdAt":"2026-06-23T16:45:53.314Z","updatedAt":"2026-06-23T16:45:53.873Z","description":"lib command currently only threads commands/events/models/queries to rust/ts linkml gen. Extend to environment/telemetry schema dirs + non-Python context emission.","blockedBy":["dizzy-d4b7"]}
+{"id":"dizzy-bb64","title":"scaffold generators emit invalid YAML for multi-line descriptions","status":"closed","type":"bug","priority":2,"createdAt":"2026-06-23T16:52:50.546Z","updatedAt":"2026-06-23T17:36:31.113Z","description":"commands.py, events.py, queries.py, models.py render 'description: {text}' inline; a multi-line | block from the feat file produces unindented continuation lines = invalid YAML (breaks generate static). Fixed in environment.py/telemetry.py via generators/yaml_util.description_lines; route the other scaffold generators through the same helper (will update their snapshots).","closedAt":"2026-06-23T17:36:31.113Z"}
+{"id":"dizzy-bb86","title":"Resolve ~30 ty type-check diagnostics (advisory CI)","status":"open","type":"task","priority":3,"createdAt":"2026-06-25T14:49:38.724Z","updatedAt":"2026-06-25T14:49:38.724Z","description":"The quality job in ci.yml runs ty as advisory. ~30 diagnostics remain across dizzy/src/dizzy and dizzy/tests (mostly Optional/None-sized access like config.policies[0] where the field is list|None). Fix these so the advisory quality job goes green; consider then promoting ty to a required check. Introduced alongside the CI/release pipeline (PR pnnl/dizzy#23)."}

CHANGELOG.md

@@ -0,0 +1,41 @@
+# 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).
+
+## [Unreleased]
+
+### Added
+- **Feature-file format** (`.feat.yaml`): a single artifact declaring a domain
+  as commands, events, procedures, policies, projections, models, and queries —
+  the reactivity loop (commands → procedures → events → policies) and the data
+  loop (events → projections → models → queries).
+- **`dizzy generate`** — the three-stage pipeline from a feature-file:
+  `definitions` (LinkML `def/` schema stubs), `static` (the `gen_def/` and
+  `gen_int/` typed-contract packages), and `libraries` (per-runtime
+  implementation-stub packages driven by `libconfig.yaml`).
+- **Runtime targets**: `python-uv` (most complete), plus experimental
+  `rust-cargo` and `typescript-npm` generators; model adapters (e.g. `sqla`).
+- **`dizzy simulate`** — LLM-driven execution of a feature-file against a
+  scenario (level 0).
+- **`dizzy onboard` / `docs` / `config`** — agent-facing project overview, the
+  CLI + authoring documentation, and a config template.
+- **Worked examples**: a fully implemented, runnable `guestbook`, plus
+  `recipes`, `library`, and `agent` feature-files.
+- Trunk-based CI (`ci.yml`): tests gate every PR; ruff lint/format and `ty`
+  type checks run as advisory signal.
+- Tag-driven release pipeline (`release.yml`): a `v*` tag builds the sdist +
+  wheel and cuts a GitHub Release with those artifacts attached.
+- `CONTRIBUTING.md` documenting the dev setup, quality gates, and release flow.
+- `ruff` (lint + format) and `ty` added to the dev dependency group, with
+  `just lint`, `just fmt`, `just fmt-check`, `just ci`, and `just build`
+  recipes.
+
+### Changed
+- Package version is now derived from git tags via `hatch-vcs` instead of being
+  hardcoded in `pyproject.toml` and `__init__.py`.
+- `pyproject.toml` gained release metadata (license, authors, classifiers, URLs).
+
+[Unreleased]: https://github.com/PNNL/dizzy/compare/HEAD

CONTRIBUTING.md

@@ -0,0 +1,80 @@
+# Contributing to DIZZY
+
+Thanks for helping! This project is **trunk-based**: `main` is always
+releasable, and all work lands through short-lived branches and pull requests.
+
+## Development setup
+
+DIZZY uses [`uv`](https://docs.astral.sh/uv/) and [`just`](https://just.systems/).
+
+```sh
+git clone https://github.com/PNNL/dizzy
+cd dizzy
+uv sync            # install deps + dev tools into .venv
+just install       # optional: install the `dizzy` CLI as an editable tool
+dizzy onboard      # read this before touching generators
+```
+
+## The workflow
+
+1. **Branch off `main`** — keep branches short-lived and focused:
+   `git switch -c my-change`.
+2. **Make the change.** Match the surrounding code style.
+3. **Run the gates locally** (see below).
+4. **Open a PR into `main`.** CI runs automatically.
+5. **Squash-merge once green.** Keep `main` linear and releasable.
+
+We track issues with [Seeds](https://github.com/jayminwest/seeds). Run
+`sd prime` at the start of a session and `sd ready` to find unblocked work.
+
+## Quality gates
+
+`just ci` runs everything CI runs, in the same order:
+
+| Command          | Tool   | Blocks merge? |
+| ---------------- | ------ | ------------- |
+| `just test`      | pytest + syrupy snapshots | **Yes** |
+| `just lint`      | ruff (lint) | No — advisory |
+| `just fmt-check` | ruff (format) | No — advisory |
+| `just check`     | `ty` (type check) | No — advisory |
+
+- **Tests are the gate.** A PR must pass `pytest` on Python 3.11–3.13 to merge.
+  In branch protection, mark the `test (py3.x)` checks as required.
+- **Lint / format / type checks are advisory.** They run in the `quality` job
+  and report status, but are *not* required checks, so they won't block a merge
+  while we adopt them across the codebase. Please still fix what you can —
+  `just fmt` auto-formats, and `just lint` shows lint findings.
+- If you intentionally re-snapshot, use `just test-update` and review the diff.
+- Touching generators? Regenerate examples and confirm no drift:
+  `just examples-check`.
+
+## Documentation
+
+- `docs/cli.md` and `docs/authoring.md` are the authoritative docs (symlinked
+  into the package so they ship in the wheel — **edit the `docs/` copies**).
+  When scope changes, change `docs/cli.md` first, then the seeds.
+- The whitepaper/architecture Typst files are maintainer-authored; you may
+  fact-check them, but don't author them.
+
+## Releasing (maintainers)
+
+Versions come from git tags via `hatch-vcs` — there is **no** version number to
+edit in source. To cut a release:
+
+1. **Update the changelog.** In `CHANGELOG.md`, rename the `[Unreleased]`
+   section to the new version with today's date, and start a fresh
+   `[Unreleased]` block above it. Keep entries grouped under
+   Added / Changed / Fixed / Removed.
+2. **Land it on `main`** via PR, as usual.
+3. **Tag and push** from `main`:
+   ```sh
+   git switch main && git pull
+   git tag v0.2.0
+   git push origin v0.2.0
+   ```
+4. The **Release** workflow takes over: it verifies the tag matches the built
+   version, builds the sdist + wheel, and creates a GitHub Release with those
+   artifacts attached.
+
+Tags are `vMAJOR.MINOR.PATCH` following [SemVer](https://semver.org/). To test a
+build without releasing, run `just build` — artifacts land in `dist/`.

dizzy/src/dizzy/__init__.py

@@ -1,3 +1,13 @@
 """Dizzy core library."""
 
-__version__ = "0.1.0"
+try:
+    # Written at build time by hatch-vcs from the git tag.
+    from ._version import __version__
+except ImportError:  # pragma: no cover - source checkout without a build
+    from importlib.metadata import PackageNotFoundError
+    from importlib.metadata import version as _version
+
+    try:
+        __version__ = _version("dizzy")
+    except PackageNotFoundError:
+        __version__ = "0.0.0+unknown"