utterplan 0.1.2__tar.gz → 0.2.0__tar.gz

{utterplan-0.1.2 → utterplan-0.2.0}/.github/workflows/codecov.yml

@@ -17,7 +17,7 @@ jobs:
           python -m pip install --upgrade pip
           python -m pip install coverage pytest pytest-cov
           python -m pip install -e ".[dev]"
-          python -m pytest -m "not reference" --cov=utterplan --cov-report=xml --junitxml=junit.xml
+          python -m pytest --cov=utterplan --cov-report=xml --junitxml=junit.xml
       - name: Upload coverage to Codecov
         uses: codecov/codecov-action@v5
         with:

{utterplan-0.1.2 → utterplan-0.2.0}/.github/workflows/tests.yml

@@ -30,7 +30,7 @@ jobs:
         if: matrix.os == 'ubuntu-latest' && matrix.python-version == '3.13'
         run: python -m ruff check .
       - name: Run tests
-        run: python -m pytest -q -m "not reference"
+        run: python -m pytest -q
 
   lower-bounds:
     runs-on: ubuntu-latest
@@ -51,7 +51,7 @@ jobs:
             "typing_extensions>=4.0"
           python -m pip install --no-deps -e .
       - name: Run lower-bound tests
-        run: python -m pytest -q -m "not reference"
+        run: python -m pytest -q
 
   package-smoke:
     runs-on: ubuntu-latest

{utterplan-0.1.2 → utterplan-0.2.0}/.gitignore

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

{utterplan-0.1.2 → utterplan-0.2.0}/.ledger/releaseledger/data/ledgers/main/events/events.jsonl

@@ -18,3 +18,21 @@
 {"data":{"changed_releases":["0.1.0","0.1.1","0.1.2"]},"event":"release.chain_repaired","event_id":"event-0018","record_revisions":{"release:0.1.0":9,"release:0.1.1":4,"release:0.1.2":5},"schema_version":2}
 {"data":{"kind":"changed","status":"accepted"},"entry_id":"entry-0001","event":"entry.added","event_id":"event-0019","record_revisions":{"entry:0.1.1/entry-0001":1,"release:0.1.1":5},"release_version":"0.1.1","schema_version":2}
 {"data":{"fields":["git_base_ref","git_base_sha","git_commit_count","git_range"]},"event":"release.updated","event_id":"event-0020","record_revisions":{"release:0.1.1":6},"release_version":"0.1.1","schema_version":2}
+{"data":{"audit_rewritten":true,"old_release_version":"0.1.2","reason":null,"replace_canceled_target":false,"rewrote_successors":false},"event":"release.renamed","event_id":"event-0021","record_revisions":{"audit:0.1.3":4,"entry:0.1.3/entry-0001":2,"entry:0.1.3/entry-0002":2,"entry:0.1.3/entry-0003":2,"release:0.1.3":6},"release_version":"0.1.3","schema_version":2}
+{"data":{"fields":["git_commit_count","git_head_sha","git_range"]},"event":"release.updated","event_id":"event-0022","record_revisions":{"release:0.1.3":7},"release_version":"0.1.3","schema_version":2}
+{"data":{"new_rows":3,"preserved_reviewed_rows":3,"removed_rows":0},"event":"audit.updated","event_id":"event-0023","record_revisions":{"commit_audit_sheet":5},"release_version":"0.1.3","schema_version":2}
+{"data":{"kind":"docs","status":"accepted"},"entry_id":"entry-0004","event":"entry.added","event_id":"event-0024","record_revisions":{"entry:0.1.3/entry-0004":1,"release:0.1.3":8},"release_version":"0.1.3","schema_version":2}
+{"data":{"kind":"internal","status":"accepted"},"entry_id":"entry-0005","event":"entry.added","event_id":"event-0025","record_revisions":{"entry:0.1.3/entry-0005":1,"release:0.1.3":9},"release_version":"0.1.3","schema_version":2}
+{"data":{"kind":"changed","status":"accepted"},"entry_id":"entry-0006","event":"entry.added","event_id":"event-0026","record_revisions":{"entry:0.1.3/entry-0006":1,"release:0.1.3":10},"release_version":"0.1.3","schema_version":2}
+{"data":{"added_source_refs":[],"fields":["summary"],"removed_source_refs":[],"source_refs_mode":"unchanged"},"entry_id":"entry-0004","event":"entry.updated","event_id":"event-0027","record_revisions":{"entry:0.1.3/entry-0004":2},"release_version":"0.1.3","schema_version":2}
+{"data":{"added_source_refs":[],"fields":["kind"],"removed_source_refs":[],"source_refs_mode":"unchanged"},"entry_id":"entry-0006","event":"entry.updated","event_id":"event-0028","record_revisions":{"entry:0.1.3/entry-0006":2},"release_version":"0.1.3","schema_version":2}
+{"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}

{utterplan-0.1.2/.ledger/releaseledger/data/ledgers/main/releases/0.1.2 → utterplan-0.2.0/.ledger/releaseledger/data/ledgers/main/releases/0.1.3}/audit/commit-audit.yaml

@@ -2,14 +2,14 @@ schema_version: 1
 object_type: commit_audit_sheet
 versioning:
   schema_version: 1
-  revision: 3
-release_version: 0.1.2
+  revision: 6
+release_version: 0.1.3
 git_base_ref: v0.1.1
 git_base_sha: a56a3513d403d3d3e0eddccc10990f32d1a1b367
 git_head_ref: HEAD
-git_head_sha: 66a88b6a7fbe4cf9e0247cfd81675050f5934fea
-git_range: a56a3513d403d3d3e0eddccc10990f32d1a1b367..66a88b6a7fbe4cf9e0247cfd81675050f5934fea
-commit_count: 3
+git_head_sha: 7cd977966475fd9c03056e5f25aaffd3501a846d
+git_range: a56a3513d403d3d3e0eddccc10990f32d1a1b367..7cd977966475fd9c03056e5f25aaffd3501a846d
+commit_count: 6
 rows:
   - sha: 402275374979b9372c1491072c4e29b642da523f
     source_ref: git:402275374979b9372c1491072c4e29b642da523f
@@ -162,3 +162,96 @@ rows:
     target_entry_key: entry-0003
     target_entry_id: entry-0003
     notes: ""
+  - sha: c31f53fb4ded2a0e805ad5f75b20cf98e47fb169
+    source_ref: git:c31f53fb4ded2a0e805ad5f75b20cf98e47fb169
+    short_sha: c31f53f
+    changed_paths:
+      - .ledger/releaseledger/data/ledgers/main/events/events.jsonl
+      - .ledger/releaseledger/data/ledgers/main/releases/0.1.0/release.md
+      - .ledger/releaseledger/data/ledgers/main/releases/0.1.1/entries/entry-0001.md
+      - .ledger/releaseledger/data/ledgers/main/releases/0.1.1/release.md
+      - .ledger/releaseledger/data/ledgers/main/releases/0.1.2/audit/commit-audit.yaml
+      - .ledger/releaseledger/data/ledgers/main/releases/0.1.2/entries/entry-0001.md
+      - .ledger/releaseledger/data/ledgers/main/releases/0.1.2/entries/entry-0002.md
+      - .ledger/releaseledger/data/ledgers/main/releases/0.1.2/entries/entry-0003.md
+      - .ledger/releaseledger/data/ledgers/main/releases/0.1.2/release.md
+      - .ledger/releaseledger/work/0.1.2/audit-decisions.yaml
+      - .ledger/releaseledger/work/0.1.2/audit.yaml
+      - .ledger/releaseledger/work/0.1.2/entries.yaml
+      - .ledger/releaseledger/work/0.1.2/evidence/2c64e29.patch
+      - .ledger/releaseledger/work/0.1.2/evidence/4022753.patch
+      - .ledger/releaseledger/work/0.1.2/evidence/66a88b6.patch
+      - .ledger/releaseledger/work/0.1.2/evidence/manifest.json
+      - .ledger/releaseledger/work/0.1.2/range.json
+      - .ledger/releaseledger/write.lock
+      - docs/changelog.md
+      - tests/test_cli.py
+      - tests/test_migration_framework.py
+      - utterplan/cli.py
+      - utterplan/exceptions.py
+      - utterplan/migration.py
+    stats:
+      files_changed: 24
+      insertions: 5851
+      deletions: 18
+    inspected: true
+    inspected_paths:
+      - docs/changelog.md
+    observed_behavior:
+      Updated changelog with release entries for v0.1.0, v0.1.1, and
+      v0.1.2
+    public_impact: docs
+    decision: accepted
+    stale: false
+    evidence_subject: "doc: changelog"
+    target_entry_id: entry-0004
+  - sha: 972d21bdfefcdc7ee04fc0d9ce00d1143dda4e78
+    source_ref: git:972d21bdfefcdc7ee04fc0d9ce00d1143dda4e78
+    short_sha: 972d21b
+    changed_paths:
+      - tests/reference/dump_pykokoro_frontend.py
+    stats:
+      files_changed: 1
+      insertions: 11
+      deletions: 1
+    inspected: true
+    inspected_paths:
+      - tests/reference/dump_pykokoro_frontend.py
+    observed_behavior: Fixed obsolete migration test for PyKokoro frontend dump
+    public_impact: none
+    decision: accepted
+    stale: false
+    evidence_subject: "test: fix obsolete migration test"
+    target_entry_id: entry-0005
+  - sha: 7cd977966475fd9c03056e5f25aaffd3501a846d
+    source_ref: git:7cd977966475fd9c03056e5f25aaffd3501a846d
+    short_sha: 7cd9779
+    changed_paths:
+      - .github/workflows/codecov.yml
+      - .github/workflows/tests.yml
+      - AGENTS.md
+      - README.md
+      - docs/conf.py
+      - docs/phase-a-completion.md
+      - docs/pykokoro-integration.md
+      - docs/pykokoro-reference.md
+      - tests/migration/test_semantic_migration_regressions.py
+      - tests/reference/__init__.py
+      - tests/reference/cases.py
+      - tests/reference/dump_pykokoro_frontend.py
+      - tests/reference/test_pykokoro_parity.py
+    stats:
+      files_changed: 13
+      insertions: 22
+      deletions: 611
+    inspected: true
+    inspected_paths:
+      - docs/pykokoro-reference.md
+      - tests/reference/dump_pykokoro_frontend.py
+      - tests/reference/test_pykokoro_parity.py
+    observed_behavior: Removed PyKokoro references and related test infrastructure
+    public_impact: public
+    decision: accepted
+    stale: false
+    evidence_subject: "feat: remove ref to pykokoro"
+    target_entry_id: entry-0006

{utterplan-0.1.2/.ledger/releaseledger/data/ledgers/main/releases/0.1.2 → utterplan-0.2.0/.ledger/releaseledger/data/ledgers/main/releases/0.1.3}/entries/entry-0001.md

@@ -3,9 +3,9 @@ schema_version: 2
 object_type: release_entry
 versioning:
   schema_version: 1
-  revision: 1
+  revision: 2
 entry_id: entry-0001
-release_version: 0.1.2
+release_version: 0.1.3
 kind: added
 summary:
   Added explain CLI command that renders compiled plans as human-readable speech

{utterplan-0.1.2/.ledger/releaseledger/data/ledgers/main/releases/0.1.2 → utterplan-0.2.0/.ledger/releaseledger/data/ledgers/main/releases/0.1.3}/entries/entry-0002.md

@@ -3,9 +3,9 @@ schema_version: 2
 object_type: release_entry
 versioning:
   schema_version: 1
-  revision: 1
+  revision: 2
 entry_id: entry-0002
-release_version: 0.1.2
+release_version: 0.1.3
 kind: changed
 summary:
   Improved consumer contract with stable renderer input view and directive

{utterplan-0.1.2/.ledger/releaseledger/data/ledgers/main/releases/0.1.2 → utterplan-0.2.0/.ledger/releaseledger/data/ledgers/main/releases/0.1.3}/entries/entry-0003.md

@@ -3,9 +3,9 @@ schema_version: 2
 object_type: release_entry
 versioning:
   schema_version: 1
-  revision: 1
+  revision: 2
 entry_id: entry-0003
-release_version: 0.1.2
+release_version: 0.1.3
 kind: added
 summary: Added schema versioning with frozen v1 schema and migration framework
 status: accepted

utterplan-0.2.0/.ledger/releaseledger/data/ledgers/main/releases/0.1.3/entries/entry-0004.md

@@ -0,0 +1,25 @@
+---
+schema_version: 2
+object_type: release_entry
+versioning:
+  schema_version: 1
+  revision: 2
+entry_id: entry-0004
+release_version: 0.1.3
+kind: docs
+summary: Documented changelog with release entries for v0.1.0, v0.1.1, and v0.1.2
+status: accepted
+audience: null
+scopes: []
+source_refs:
+  - git:c31f53fb4ded2a0e805ad5f75b20cf98e47fb169
+paths:
+  - docs/changelog.md
+issues: []
+prs: []
+sources: []
+contributors: []
+breaking: false
+internal: false
+order: 4
+---

utterplan-0.2.0/.ledger/releaseledger/data/ledgers/main/releases/0.1.3/entries/entry-0005.md

@@ -0,0 +1,25 @@
+---
+schema_version: 2
+object_type: release_entry
+versioning:
+  schema_version: 1
+  revision: 2
+entry_id: entry-0005
+release_version: 0.1.3
+kind: quality
+summary: Fixed obsolete migration test for PyKokoro frontend dump
+status: accepted
+audience: null
+scopes: []
+source_refs:
+  - git:972d21bdfefcdc7ee04fc0d9ce00d1143dda4e78
+paths:
+  - tests/reference/dump_pykokoro_frontend.py
+issues: []
+prs: []
+sources: []
+contributors: []
+breaking: false
+internal: false
+order: 5
+---

utterplan-0.2.0/.ledger/releaseledger/data/ledgers/main/releases/0.1.3/entries/entry-0006.md

@@ -0,0 +1,27 @@
+---
+schema_version: 2
+object_type: release_entry
+versioning:
+  schema_version: 1
+  revision: 2
+entry_id: entry-0006
+release_version: 0.1.3
+kind: removed
+summary: Removed PyKokoro references and related test infrastructure
+status: accepted
+audience: null
+scopes: []
+source_refs:
+  - git:7cd977966475fd9c03056e5f25aaffd3501a846d
+paths:
+  - docs/pykokoro-reference.md
+  - tests/reference/dump_pykokoro_frontend.py
+  - tests/reference/test_pykokoro_parity.py
+issues: []
+prs: []
+sources: []
+contributors: []
+breaking: false
+internal: false
+order: 6
+---

{utterplan-0.1.2/.ledger/releaseledger/data/ledgers/main/releases/0.1.2 → utterplan-0.2.0/.ledger/releaseledger/data/ledgers/main/releases/0.1.3}/release.md

@@ -3,12 +3,12 @@ schema_version: 2
 object_type: release
 versioning:
   schema_version: 1
-  revision: 5
-version: 0.1.2
-status: planned
+  revision: 11
+version: 0.1.3
+status: released
 history_state: curated
 title: null
-released_at: null
+released_at: "2026-09-19"
 previous_version: 0.1.1
 cancel_reason: null
 superseded_by: null
@@ -16,12 +16,12 @@ changelog_file: null
 boundary_ref: null
 source_refs: []
 source_count: null
-entry_count: 3
+entry_count: 6
 artifact_count: 0
 git_base_ref: v0.1.1
 git_base_sha: a56a3513d403d3d3e0eddccc10990f32d1a1b367
 git_head_ref: HEAD
-git_head_sha: 66a88b6a7fbe4cf9e0247cfd81675050f5934fea
-git_range: a56a3513d403d3d3e0eddccc10990f32d1a1b367..66a88b6a7fbe4cf9e0247cfd81675050f5934fea
-git_commit_count: 3
+git_head_sha: 7cd977966475fd9c03056e5f25aaffd3501a846d
+git_range: a56a3513d403d3d3e0eddccc10990f32d1a1b367..7cd977966475fd9c03056e5f25aaffd3501a846d
+git_commit_count: 6
 ---

utterplan-0.2.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.2.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.