utterplan 0.1.3__tar.gz → 0.3.0__tar.gz

{utterplan-0.1.3 → utterplan-0.3.0}/.github/workflows/python-publish.yml

@@ -45,18 +45,21 @@ jobs:
           from packaging.requirements import Requirement
           from packaging.version import Version
 
-          def has_minimum(requirements, name, minimum):
+          def has_range(requirements, name, minimum, maximum):
               minimum_version = Version(minimum)
+              maximum_version = Version(maximum)
               return any(
                   requirement.name == name
                   and any(
-                      spec.operator in (">=", ">", "==")
-                      and Version(spec.version) >= minimum_version
+                      spec.operator == ">=" and Version(spec.version) == minimum_version
+                      for spec in requirement.specifier
+                  )
+                  and any(
+                      spec.operator == "<" and Version(spec.version) == maximum_version
                       for spec in requirement.specifier
                   )
                   for requirement in requirements
               )
-
           tag_version = os.environ["RELEASE_TAG"].removeprefix("v")
           artifacts = list(Path("dist").iterdir())
           wheels = [path for path in artifacts if path.suffix == ".whl"]
@@ -76,11 +79,18 @@ jobs:
               requirements = [
                   Requirement(value) for value in metadata.get_all("Requires-Dist", [])
               ]
-              assert has_minimum(requirements, "phrasplit", "0.3.9")
-              assert has_minimum(requirements, "ssmd", "0.8.7")
-              assert has_minimum(requirements, "spokenform", "0.4.3")
-              assert any(name.endswith("utterplan/py.typed") for name in archive.namelist())
-              assert any(name.endswith("utterplan/utterplan.schema.json") for name in archive.namelist())
+              assert has_range(requirements, "phrasplit", "0.3.9", "0.4")
+              assert has_range(requirements, "ssmd", "0.9.0", "0.10")
+              assert has_range(requirements, "spokenform", "0.4.3", "0.5")
+              names = set(archive.namelist())
+              expected = {
+                  "utterplan/py.typed",
+                  "utterplan/utterplan.schema.json",
+                  "utterplan/schemas/v1.schema.json",
+                  "utterplan/schemas/v2.schema.json",
+                  "utterplan/schemas/v3.schema.json",
+              }
+              assert expected <= names
           PY
 
       - name: Publish package to PyPI

utterplan-0.3.0/.github/workflows/tests.yml

@@ -0,0 +1,177 @@
+name: Run tests
+
+on:
+  push:
+  pull_request:
+  workflow_call:
+
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
+        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install package
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install -e ".[dev]"
+          python -m compileall -q utterplan tests
+      - name: Type-check package
+        if: matrix.os == 'ubuntu-latest' && matrix.python-version == '3.13'
+        run: python -m mypy utterplan
+      - name: Lint package
+        if: matrix.os == 'ubuntu-latest' && matrix.python-version == '3.13'
+        run: python -m ruff check .
+      - name: Run tests
+        run: python -m pytest -q
+
+  lower-bounds:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.10"
+      - name: Install lower-bound dependencies
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install pytest jsonschema
+          python -m pip install \
+            "phrasplit==0.3.9" \
+            "ssmd==0.9.0" \
+            "spokenform==0.4.3" \
+            "typing_extensions>=4.0"
+          python -m pip install --no-deps -e .
+      - name: Run lower-bound tests
+        run: python -m pytest -q
+
+  package-smoke:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Build wheel and sdist
+        run: |
+          python -m pip install --upgrade pip build
+          python -m build --outdir "$RUNNER_TEMP/dist"
+      - name: Verify wheel and sdist contents and dependency metadata
+        run: |
+          python - <<'PY'
+          import os
+          import tarfile
+          from email import policy
+          from email.parser import Parser
+          from pathlib import Path
+          from zipfile import ZipFile
+
+          from packaging.requirements import Requirement
+          from packaging.version import Version
+
+          artifacts = Path(os.environ["RUNNER_TEMP"]) / "dist"
+          wheel = next(artifacts.glob("*.whl"))
+          sdist = next(artifacts.glob("*.tar.gz"))
+          expected = {
+              "utterplan/py.typed",
+              "utterplan/utterplan.schema.json",
+              "utterplan/schemas/v1.schema.json",
+              "utterplan/schemas/v2.schema.json",
+              "utterplan/schemas/v3.schema.json",
+          }
+          expected_ranges = {
+              "phrasplit": ("0.3.9", "0.4"),
+              "ssmd": ("0.9.0", "0.10"),
+              "spokenform": ("0.4.3", "0.5"),
+          }
+
+          def check_metadata(contents):
+              metadata = Parser(policy=policy.default).parsestr(contents)
+              requirements = metadata.get_all("Requires-Dist", [])
+              for name, (minimum, maximum) in expected_ranges.items():
+                  requirement = next(
+                      Requirement(value)
+                      for value in requirements
+                      if Requirement(value).name == name
+                  )
+                  assert any(
+                      spec.operator == ">=" and Version(spec.version) == Version(minimum)
+                      for spec in requirement.specifier
+                  ), (name, requirement)
+                  assert any(
+                      spec.operator == "<" and Version(spec.version) == Version(maximum)
+                      for spec in requirement.specifier
+                  ), (name, requirement)
+
+          with ZipFile(wheel) as archive:
+              wheel_names = set(archive.namelist())
+              assert expected <= wheel_names
+              metadata_name = next(
+                  name for name in wheel_names if name.endswith("METADATA")
+              )
+              check_metadata(archive.read(metadata_name).decode("utf-8"))
+
+          with tarfile.open(sdist, "r:gz") as archive:
+              sdist_names = archive.getnames()
+              assert all(
+                  any(name.endswith(resource) for name in sdist_names)
+                  for resource in expected
+              )
+              metadata_name = next(
+                  name for name in sdist_names if name.endswith("PKG-INFO")
+              )
+              check_metadata(
+                  archive.extractfile(metadata_name).read().decode("utf-8")
+              )
+          PY
+      - name: Install wheel in clean environment
+        run: |
+          python -m venv "$RUNNER_TEMP/utterplan-wheel-venv"
+          "$RUNNER_TEMP/utterplan-wheel-venv/bin/python" -m pip install \
+            "$RUNNER_TEMP"/dist/utterplan-*.whl
+      - name: Run installed smoke checks
+        run: |
+          "$RUNNER_TEMP/utterplan-wheel-venv/bin/python" -c \
+            "import importlib.metadata as m; import utterplan; assert m.version('utterplan') == utterplan.__version__"
+          "$RUNNER_TEMP/utterplan-wheel-venv/bin/utterplan" --version
+          cat > "$RUNNER_TEMP/test.ssmd.md" <<'EOF'
+          ---
+          ssmd_version: "0.9"
+          language: en-US
+          pause_defaults:
+            sentence: 500ms
+          ---
+          [Hello]{voice-name="test"} ...200ms world.
+          EOF
+          "$RUNNER_TEMP/utterplan-wheel-venv/bin/utterplan" compile \
+            "$RUNNER_TEMP/test.ssmd.md" --lang en-us --text-preparation identity --json \
+            > "$RUNNER_TEMP/test.utterplan.json"
+          "$RUNNER_TEMP/utterplan-wheel-venv/bin/utterplan" validate \
+            "$RUNNER_TEMP/test.utterplan.json"
+          cat > "$RUNNER_TEMP/test-0.8.ssmd.md" <<'EOF'
+          ---
+          ssmd_version: "0.8"
+          ---
+          Hello.
+          EOF
+          if "$RUNNER_TEMP/utterplan-wheel-venv/bin/utterplan" compile \
+            "$RUNNER_TEMP/test-0.8.ssmd.md" --lang en-us --text-preparation identity --json \
+            > "$RUNNER_TEMP/test-0.8.out" 2>&1; then
+            cat "$RUNNER_TEMP/test-0.8.out"
+            echo "Installed wheel accepted an SSMD 0.8 document" >&2
+            exit 1
+          fi
+          grep -q "header.version_unsupported" "$RUNNER_TEMP/test-0.8.out"
+          "$RUNNER_TEMP/utterplan-wheel-venv/bin/utterplan" migrate \
+            "$GITHUB_WORKSPACE/tests/schema_history/v1/basic.json" --check
+          "$RUNNER_TEMP/utterplan-wheel-venv/bin/utterplan" inspect \
+            "$RUNNER_TEMP/test.utterplan.json" --segment 0

{utterplan-0.1.3 → utterplan-0.3.0}/.gitignore

@@ -219,3 +219,6 @@ __marimo__/
 context_utterplan*.*
 
 utterplan/_version.py
+
+# Generated outputs from the runnable examples
+examples/*.utterplan.json

{utterplan-0.1.3 → utterplan-0.3.0}/.ledger/releaseledger/data/ledgers/main/events/events.jsonl

@@ -29,3 +29,15 @@
 {"data":{"added_source_refs":[],"fields":["internal","kind"],"removed_source_refs":[],"source_refs_mode":"unchanged"},"entry_id":"entry-0005","event":"entry.updated","event_id":"event-0029","record_revisions":{"entry:0.1.3/entry-0005":2},"release_version":"0.1.3","schema_version":2}
 {"data":{"updated_rows":3},"event":"audit.updated","event_id":"event-0030","record_revisions":{"commit_audit_sheet":6},"release_version":"0.1.3","schema_version":2}
 {"data":{"released_at":"2026-09-19"},"event":"release.finalized","event_id":"event-0031","record_revisions":{"release:0.1.3":11},"release_version":"0.1.3","schema_version":2}
+{"data":{"status":"planned"},"event":"release.created","event_id":"event-0032","record_revisions":{"release:0.2.0":1},"release_version":"0.2.0","schema_version":2}
+{"data":{"fields":["git_base_ref","git_base_sha","git_commit_count","git_head_ref","git_head_sha","git_range"]},"event":"release.updated","event_id":"event-0033","record_revisions":{"release:0.2.0":2},"release_version":"0.2.0","schema_version":2}
+{"data":{"row_count":3},"event":"audit.created","event_id":"event-0034","record_revisions":{"commit_audit_sheet":1},"release_version":"0.2.0","schema_version":2}
+{"data":{"updated_rows":3},"event":"audit.updated","event_id":"event-0035","record_revisions":{"commit_audit_sheet":2},"release_version":"0.2.0","schema_version":2}
+{"data":{"updated_rows":3},"event":"audit.updated","event_id":"event-0036","record_revisions":{"commit_audit_sheet":3},"release_version":"0.2.0","schema_version":2}
+{"data":{"entry_ids":["entry-0001","entry-0002","entry-0003","entry-0004"],"synced_audit_rows":3},"event":"entry.batch_added","event_id":"event-0037","record_revisions":{"commit_audit_sheet":4,"entry:0.2.0/entry-0001":1,"entry:0.2.0/entry-0002":1,"entry:0.2.0/entry-0003":1,"entry:0.2.0/entry-0004":1,"release:0.2.0":3},"release_version":"0.2.0","schema_version":2}
+{"data":{"released_at":"2026-09-22"},"event":"release.finalized","event_id":"event-0038","record_revisions":{"release:0.2.0":4},"release_version":"0.2.0","schema_version":2}
+{"data":{"status":"planned"},"event":"release.created","event_id":"event-0039","record_revisions":{"release:0.3.0":1},"release_version":"0.3.0","schema_version":2}
+{"data":{"fields":["git_base_ref","git_base_sha","git_commit_count","git_head_ref","git_head_sha","git_range"]},"event":"release.updated","event_id":"event-0040","record_revisions":{"release:0.3.0":2},"release_version":"0.3.0","schema_version":2}
+{"data":{"row_count":1},"event":"audit.created","event_id":"event-0041","record_revisions":{"commit_audit_sheet":1},"release_version":"0.3.0","schema_version":2}
+{"data":{"updated_rows":1},"event":"audit.updated","event_id":"event-0042","record_revisions":{"commit_audit_sheet":2},"release_version":"0.3.0","schema_version":2}
+{"data":{"entry_ids":["entry-0001","entry-0002","entry-0003","entry-0004","entry-0005","entry-0006"],"synced_audit_rows":1},"event":"entry.batch_added","event_id":"event-0043","record_revisions":{"commit_audit_sheet":3,"entry:0.3.0/entry-0001":1,"entry:0.3.0/entry-0002":1,"entry:0.3.0/entry-0003":1,"entry:0.3.0/entry-0004":1,"entry:0.3.0/entry-0005":1,"entry:0.3.0/entry-0006":1,"release:0.3.0":3},"release_version":"0.3.0","schema_version":2}

utterplan-0.3.0/.ledger/releaseledger/data/ledgers/main/releases/0.2.0/audit/commit-audit.yaml

@@ -0,0 +1,241 @@
+schema_version: 1
+object_type: commit_audit_sheet
+versioning:
+  schema_version: 1
+  revision: 4
+release_version: 0.2.0
+git_base_ref: v0.1.3
+git_base_sha: 35a631ed89a676484546d62bccf08203f93b01e9
+git_head_ref: HEAD
+git_head_sha: 9637182acbf51763706e1047283b6df27def4bb8
+git_range: 35a631ed89a676484546d62bccf08203f93b01e9..9637182acbf51763706e1047283b6df27def4bb8
+commit_count: 3
+rows:
+  - sha: e49a6ddc97c789574098a635fc823da885b48439
+    source_ref: git:e49a6ddc97c789574098a635fc823da885b48439
+    short_sha: e49a6dd
+    changed_paths:
+      - .gitignore
+      - examples/basic.py
+      - examples/chapter.ssmd
+      - examples/compile_file.py
+      - examples/inspect_plan.py
+      - examples/multilingual.py
+      - examples/ssmd.py
+      - examples/ssmd_example.py
+    stats:
+      files_changed: 8
+      insertions: 93
+      deletions: 19
+    inspected: true
+    inspected_paths:
+      - .gitignore
+      - examples/basic.py
+      - examples/chapter.ssmd
+      - examples/compile_file.py
+      - examples/inspect_plan.py
+      - examples/multilingual.py
+      - examples/ssmd.py
+      - examples/ssmd_example.py
+    observed_behavior:
+      Example scripts now run through main() entry points. basic.py,
+      compile_file.py, and inspect_plan.py gained argparse interfaces with defaults
+      resolved next to the script and outputs written beside it. multilingual.py demonstrates
+      inline SSMD language switching. examples/ssmd.py was replaced by examples/ssmd_example.py,
+      examples/chapter.ssmd was added as sample SSMD input, and generated examples/*.utterplan.json
+      outputs are excluded from git.
+    public_impact: docs
+    decision: accepted
+    stale: false
+    evidence_subject: "fix: examples"
+    target_entry_id: entry-0003
+    notes:
+      Examples-only change with documentation impact; covered by the fixed entry
+      for the examples rework.
+  - sha: c52aa684cc872d348d90972001a8c5194ae7c7f8
+    source_ref: git:c52aa684cc872d348d90972001a8c5194ae7c7f8
+    short_sha: c52aa68
+    changed_paths:
+      - README.md
+      - docs/architecture.md
+      - docs/cli.md
+      - docs/consumer-guide.md
+      - docs/coordinate-spaces.md
+      - docs/debugging.md
+      - docs/format.md
+      - docs/getting-started.md
+      - docs/index.md
+      - docs/pykokoro-integration.md
+      - docs/python-api.md
+      - pyproject.toml
+      - spec/schemas/v2.schema.json
+      - spec/utterplan.schema.json
+      - tests/golden/basic_en.utterplan.json
+      - tests/golden/directives.utterplan.json
+      - tests/golden/markers.utterplan.json
+      - tests/golden/multilingual.utterplan.json
+      - tests/golden/parenthetical.utterplan.json
+      - tests/golden/spokenform_offsets.utterplan.json
+      - tests/golden/ssmd_breaks.utterplan.json
+      - tests/test_cli.py
+      - tests/test_explain.py
+      - tests/test_format.py
+      - tests/test_linguistics.py
+      - tests/test_migration_framework.py
+      - tests/test_public_identity.py
+      - tests/test_schema_history.py
+      - tests/test_schema_registry.py
+      - utterplan/__init__.py
+      - utterplan/cli.py
+      - utterplan/explain.py
+      - utterplan/hashing.py
+      - utterplan/linguistics.py
+      - utterplan/migrations/__init__.py
+      - utterplan/migrations/registry.py
+      - utterplan/migrations/v1_to_v2.py
+      - utterplan/model.py
+      - utterplan/planner.py
+      - utterplan/schema_registry.py
+      - utterplan/schemas/v2.schema.json
+      - utterplan/units.py
+      - utterplan/utterplan.schema.json
+      - utterplan/versioning.py
+    stats:
+      files_changed: 44
+      insertions: 1714
+      deletions: 215
+    inspected: true
+    inspected_paths:
+      - README.md
+      - docs/architecture.md
+      - docs/cli.md
+      - docs/consumer-guide.md
+      - docs/coordinate-spaces.md
+      - docs/debugging.md
+      - docs/format.md
+      - docs/getting-started.md
+      - docs/index.md
+      - docs/pykokoro-integration.md
+      - docs/python-api.md
+      - pyproject.toml
+      - spec/schemas/v2.schema.json
+      - spec/utterplan.schema.json
+      - tests/golden/basic_en.utterplan.json
+      - tests/golden/directives.utterplan.json
+      - tests/golden/markers.utterplan.json
+      - tests/golden/multilingual.utterplan.json
+      - tests/golden/parenthetical.utterplan.json
+      - tests/golden/spokenform_offsets.utterplan.json
+      - tests/golden/ssmd_breaks.utterplan.json
+      - tests/test_cli.py
+      - tests/test_explain.py
+      - tests/test_format.py
+      - tests/test_linguistics.py
+      - tests/test_migration_framework.py
+      - tests/test_public_identity.py
+      - tests/test_schema_history.py
+      - tests/test_schema_registry.py
+      - utterplan/__init__.py
+      - utterplan/cli.py
+      - utterplan/explain.py
+      - utterplan/hashing.py
+      - utterplan/linguistics.py
+      - utterplan/migrations/__init__.py
+      - utterplan/migrations/registry.py
+      - utterplan/migrations/v1_to_v2.py
+      - utterplan/model.py
+      - utterplan/planner.py
+      - utterplan/schema_registry.py
+      - utterplan/schemas/v2.schema.json
+      - utterplan/units.py
+      - utterplan/utterplan.schema.json
+      - utterplan/versioning.py
+    observed_behavior:
+      Serialized plans gain a v2 schema that embeds token annotations
+      with lemma, pos, tag, and morph fields plus linguistic run records carrying provider,
+      model, provider_version, and model_version provenance. Unit content hashes move
+      to the utterplan-unit-v2 payload that includes tokens. A registered v1-to-v2 migration
+      upgrades older files and the schema registry keeps v1 frozen. pyproject gains
+      a spacy optional extra. The inspect token view and detailed explain output report
+      provider and model provenance and per-segment tokens.
+    public_impact: public
+    decision: accepted
+    stale: false
+    evidence_subject: "feat: add v2 with spacy tokens embedded"
+    target_entry_id: entry-0001
+    notes:
+      "Two entries describe this commit: the schema v2 feature owns the git source
+      ref and the inspect/explain output detail references it as supporting source."
+  - sha: 9637182acbf51763706e1047283b6df27def4bb8
+    source_ref: git:9637182acbf51763706e1047283b6df27def4bb8
+    short_sha: "9637182"
+    changed_paths:
+      - docs/cli.md
+      - docs/consumer-guide.md
+      - docs/getting-started.md
+      - docs/pykokoro-integration.md
+      - docs/python-api.md
+      - spec/schemas/v2.schema.json
+      - spec/utterplan.schema.json
+      - tests/golden/basic_en.utterplan.json
+      - tests/golden/directives.utterplan.json
+      - tests/golden/markers.utterplan.json
+      - tests/golden/multilingual.utterplan.json
+      - tests/golden/parenthetical.utterplan.json
+      - tests/golden/spokenform_offsets.utterplan.json
+      - tests/golden/ssmd_breaks.utterplan.json
+      - tests/test_cli.py
+      - tests/test_format.py
+      - tests/test_linguistics.py
+      - tests/test_schema_history.py
+      - utterplan/explain.py
+      - utterplan/hashing.py
+      - utterplan/migrations/v1_to_v2.py
+      - utterplan/model.py
+      - utterplan/planner.py
+      - utterplan/schemas/v2.schema.json
+      - utterplan/utterplan.schema.json
+    stats:
+      files_changed: 25
+      insertions: 159
+      deletions: 193
+    inspected: true
+    inspected_paths:
+      - docs/cli.md
+      - docs/consumer-guide.md
+      - docs/getting-started.md
+      - docs/pykokoro-integration.md
+      - docs/python-api.md
+      - spec/schemas/v2.schema.json
+      - spec/utterplan.schema.json
+      - tests/golden/basic_en.utterplan.json
+      - tests/golden/directives.utterplan.json
+      - tests/golden/markers.utterplan.json
+      - tests/golden/multilingual.utterplan.json
+      - tests/golden/parenthetical.utterplan.json
+      - tests/golden/spokenform_offsets.utterplan.json
+      - tests/golden/ssmd_breaks.utterplan.json
+      - tests/test_cli.py
+      - tests/test_format.py
+      - tests/test_linguistics.py
+      - tests/test_schema_history.py
+      - utterplan/explain.py
+      - utterplan/hashing.py
+      - utterplan/migrations/v1_to_v2.py
+      - utterplan/model.py
+      - utterplan/planner.py
+      - utterplan/schemas/v2.schema.json
+      - utterplan/utterplan.schema.json
+    observed_behavior:
+      "Formatter-only normalization: golden fixtures compacted to single-line
+      JSON arrays, schema required arrays expanded and rewrapped, and Python modules,
+      tests, and migrations rewrapped to formatter style. Hashing, validation, migration,
+      and planning behavior are unchanged."
+    public_impact: none
+    decision: internal
+    stale: false
+    evidence_subject: "chore: pre-commit"
+    target_entry_id: entry-0004
+    notes:
+      Formatting-only change with no user-visible behavior; represented by an internal
+      entry and excluded from the public changelog.

utterplan-0.3.0/.ledger/releaseledger/data/ledgers/main/releases/0.2.0/entries/entry-0001.md

@@ -0,0 +1,74 @@
+---
+schema_version: 2
+object_type: release_entry
+versioning:
+  schema_version: 1
+  revision: 1
+entry_id: entry-0001
+release_version: 0.2.0
+kind: added
+summary:
+  Added schema version 2 with embedded token annotations, linguistic run provenance,
+  and a v1-to-v2 migration
+status: accepted
+audience: null
+scopes: []
+source_refs:
+  - git:c52aa684cc872d348d90972001a8c5194ae7c7f8
+paths:
+  - README.md
+  - docs/architecture.md
+  - docs/cli.md
+  - docs/consumer-guide.md
+  - docs/coordinate-spaces.md
+  - docs/debugging.md
+  - docs/format.md
+  - docs/getting-started.md
+  - docs/index.md
+  - docs/pykokoro-integration.md
+  - docs/python-api.md
+  - pyproject.toml
+  - spec/schemas/v2.schema.json
+  - spec/utterplan.schema.json
+  - tests/golden/basic_en.utterplan.json
+  - tests/golden/directives.utterplan.json
+  - tests/golden/markers.utterplan.json
+  - tests/golden/multilingual.utterplan.json
+  - tests/golden/parenthetical.utterplan.json
+  - tests/golden/spokenform_offsets.utterplan.json
+  - tests/golden/ssmd_breaks.utterplan.json
+  - tests/test_cli.py
+  - tests/test_explain.py
+  - tests/test_format.py
+  - tests/test_linguistics.py
+  - tests/test_migration_framework.py
+  - tests/test_public_identity.py
+  - tests/test_schema_history.py
+  - tests/test_schema_registry.py
+  - utterplan/__init__.py
+  - utterplan/cli.py
+  - utterplan/explain.py
+  - utterplan/hashing.py
+  - utterplan/linguistics.py
+  - utterplan/migrations/__init__.py
+  - utterplan/migrations/registry.py
+  - utterplan/migrations/v1_to_v2.py
+  - utterplan/model.py
+  - utterplan/planner.py
+  - utterplan/schema_registry.py
+  - utterplan/schemas/v2.schema.json
+  - utterplan/units.py
+  - utterplan/utterplan.schema.json
+  - utterplan/versioning.py
+issues: []
+prs: []
+sources:
+  - git:c52aa684cc872d348d90972001a8c5194ae7c7f8
+contributors:
+  - "@holgern"
+breaking: false
+internal: false
+order: 1
+---
+
+Serialized plans can now be written as schema version 2, which embeds token annotations with lemma, pos, tag, and morph fields and records linguistic run provenance (provider, model, provider version, model version). Unit content hashes move to the utterplan-unit-v2 payload that includes tokens. Older v1 files upgrade through the registered v1-to-v2 migration while v1 stays frozen, and spaCy support is available through the spacy optional extra.

utterplan-0.3.0/.ledger/releaseledger/data/ledgers/main/releases/0.2.0/entries/entry-0002.md

@@ -0,0 +1,31 @@
+---
+schema_version: 2
+object_type: release_entry
+versioning:
+  schema_version: 1
+  revision: 1
+entry_id: entry-0002
+release_version: 0.2.0
+kind: changed
+summary:
+  Improved inspect and explain output with token annotations and linguistic
+  run metadata
+status: accepted
+audience: null
+scopes: []
+source_refs: []
+paths:
+  - utterplan/cli.py
+  - utterplan/explain.py
+issues: []
+prs: []
+sources:
+  - git:c52aa684cc872d348d90972001a8c5194ae7c7f8
+contributors:
+  - "@holgern"
+breaking: false
+internal: false
+order: 2
+---
+
+The inspect token view reports provider and model provenance alongside per-token lemma, pos, tag, and morph values. Detailed explain output lists each segment's tokens and the linguistic run information behind them.

utterplan-0.3.0/.ledger/releaseledger/data/ledgers/main/releases/0.2.0/entries/entry-0003.md

@@ -0,0 +1,38 @@
+---
+schema_version: 2
+object_type: release_entry
+versioning:
+  schema_version: 1
+  revision: 1
+entry_id: entry-0003
+release_version: 0.2.0
+kind: fixed
+summary:
+  Fixed runnable examples with command-line arguments, path-safe outputs, and
+  a dedicated SSMD example script
+status: accepted
+audience: null
+scopes: []
+source_refs:
+  - git:e49a6ddc97c789574098a635fc823da885b48439
+paths:
+  - .gitignore
+  - examples/basic.py
+  - examples/chapter.ssmd
+  - examples/compile_file.py
+  - examples/inspect_plan.py
+  - examples/multilingual.py
+  - examples/ssmd.py
+  - examples/ssmd_example.py
+issues: []
+prs: []
+sources:
+  - git:e49a6ddc97c789574098a635fc823da885b48439
+contributors:
+  - "@holgern"
+breaking: false
+internal: false
+order: 3
+---
+
+Example scripts expose main() entry points with argparse interfaces, resolve default paths next to the script instead of the current working directory, and write generated plans beside the source. examples/ssmd.py is replaced by examples/ssmd_example.py, examples/chapter.ssmd provides sample SSMD input, and generated examples/\*.utterplan.json outputs are excluded from git.