utterplan 0.1.1__tar.gz → 0.1.2__tar.gz

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

@@ -76,6 +76,7 @@ jobs:
           names = set(ZipFile(wheel).namelist())
           assert "utterplan/py.typed" in names
           assert "utterplan/utterplan.schema.json" in names
+          assert "utterplan/schemas/v1.schema.json" in names
           PY
       - name: Install wheel in clean environment
         run: |
@@ -90,5 +91,7 @@ jobs:
           "$RUNNER_TEMP/utterplan-wheel-venv/bin/utterplan" compile \
             "Doctor Smith bought 5 kg." --lang en-us --json > "$RUNNER_TEMP/utterplan.json"
           "$RUNNER_TEMP/utterplan-wheel-venv/bin/utterplan" validate "$RUNNER_TEMP/utterplan.json"
+          "$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/utterplan.json" --segment 0

utterplan-0.1.2/.ledger/releaseledger/data/ledgers/main/events/events.jsonl

@@ -0,0 +1,20 @@
+{"data":{"status":"planned"},"event":"release.created","event_id":"event-0001","record_revisions":{"release:0.1.0":1},"release_version":"0.1.0","schema_version":2}
+{"data":{"kind":"added","status":"accepted"},"entry_id":"entry-0001","event":"entry.added","event_id":"event-0002","record_revisions":{"entry:0.1.0/entry-0001":1,"release:0.1.0":2},"release_version":"0.1.0","schema_version":2}
+{"data":{"kind":"changed","status":"accepted"},"entry_id":"entry-0002","event":"entry.added","event_id":"event-0003","record_revisions":{"entry:0.1.0/entry-0002":1,"release:0.1.0":3},"release_version":"0.1.0","schema_version":2}
+{"data":{"kind":"docs","status":"accepted"},"entry_id":"entry-0003","event":"entry.added","event_id":"event-0004","record_revisions":{"entry:0.1.0/entry-0003":1,"release:0.1.0":4},"release_version":"0.1.0","schema_version":2}
+{"data":{"kind":"quality","status":"accepted"},"entry_id":"entry-0004","event":"entry.added","event_id":"event-0005","record_revisions":{"entry:0.1.0/entry-0004":1,"release:0.1.0":5},"release_version":"0.1.0","schema_version":2}
+{"data":{"fields":["note","title"]},"event":"release.updated","event_id":"event-0006","record_revisions":{"release:0.1.0":6},"release_version":"0.1.0","schema_version":2}
+{"data":{"added_source_refs":[],"fields":["paths"],"reason":"Update release paths after package rename.","removed_source_refs":[],"source_refs_mode":"unchanged"},"entry_id":"entry-0001","event":"entry.updated","event_id":"event-0007","record_revisions":{"entry:0.1.0/entry-0001":2},"release_version":"0.1.0","schema_version":2}
+{"data":{"added_source_refs":[],"fields":["paths"],"reason":"Update release paths after package rename.","removed_source_refs":[],"source_refs_mode":"unchanged"},"entry_id":"entry-0002","event":"entry.updated","event_id":"event-0008","record_revisions":{"entry:0.1.0/entry-0002":2},"release_version":"0.1.0","schema_version":2}
+{"data":{"status":"planned"},"event":"release.created","event_id":"event-0009","record_revisions":{"release:0.1.2":1},"release_version":"0.1.2","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-0010","record_revisions":{"release:0.1.2":2},"release_version":"0.1.2","schema_version":2}
+{"data":{"row_count":3},"event":"audit.created","event_id":"event-0011","record_revisions":{"commit_audit_sheet":1},"release_version":"0.1.2","schema_version":2}
+{"data":{"updated_rows":3},"event":"audit.updated","event_id":"event-0012","record_revisions":{"commit_audit_sheet":2},"release_version":"0.1.2","schema_version":2}
+{"data":{"entry_ids":["entry-0001","entry-0002","entry-0003"],"synced_audit_rows":3},"event":"entry.batch_added","event_id":"event-0013","record_revisions":{"commit_audit_sheet":3,"entry:0.1.2/entry-0001":1,"entry:0.1.2/entry-0002":1,"entry:0.1.2/entry-0003":1,"release:0.1.2":3},"release_version":"0.1.2","schema_version":2}
+{"data":{"status":"released"},"event":"release.created","event_id":"event-0014","record_revisions":{"release:0.1.1":1},"release_version":"0.1.1","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-0015","record_revisions":{"release:0.1.1":2},"release_version":"0.1.1","schema_version":2}
+{"data":{"changed_releases":["0.1.1","0.1.0","0.1.2"]},"event":"release.chain_repaired","event_id":"event-0016","record_revisions":{"release:0.1.0":7,"release:0.1.1":3,"release:0.1.2":4},"schema_version":2}
+{"data":{"released_at":"2026-09-16"},"event":"release.finalized","event_id":"event-0017","record_revisions":{"release:0.1.0":8},"release_version":"0.1.0","schema_version":2}
+{"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}

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

@@ -3,12 +3,12 @@ schema_version: 2
 object_type: release
 versioning:
   schema_version: 1
-  revision: 6
+  revision: 9
 version: 0.1.0
-status: planned
+status: released
 history_state: curated
 title: UtterPlan v0.1.0
-released_at: null
+released_at: "2026-09-16"
 previous_version: null
 cancel_reason: null
 superseded_by: null

utterplan-0.1.2/.ledger/releaseledger/data/ledgers/main/releases/0.1.1/entries/entry-0001.md

@@ -0,0 +1,24 @@
+---
+schema_version: 2
+object_type: release_entry
+versioning:
+  schema_version: 1
+  revision: 1
+entry_id: entry-0001
+release_version: 0.1.1
+kind: changed
+summary: Renamed package from wandler to utterplan
+status: accepted
+audience: null
+scopes: []
+source_refs:
+  - git:a56a3513d403d3d3e0eddccc10990f32d1a1b367
+paths: []
+issues: []
+prs: []
+sources: []
+contributors: []
+breaking: false
+internal: false
+order: 1
+---

utterplan-0.1.2/.ledger/releaseledger/data/ledgers/main/releases/0.1.1/release.md

@@ -0,0 +1,27 @@
+---
+schema_version: 2
+object_type: release
+versioning:
+  schema_version: 1
+  revision: 6
+version: 0.1.1
+status: released
+history_state: discovered
+title: null
+released_at: "2026-09-16"
+previous_version: 0.1.0
+cancel_reason: null
+superseded_by: null
+changelog_file: null
+boundary_ref: null
+source_refs: []
+source_count: null
+entry_count: 1
+artifact_count: 0
+git_base_ref: v0.1.0
+git_base_sha: cb464479461d1b8206b14fd1abf2ca3606706d45
+git_head_ref: v0.1.1
+git_head_sha: a56a3513d403d3d3e0eddccc10990f32d1a1b367
+git_range: cb464479461d1b8206b14fd1abf2ca3606706d45..a56a3513d403d3d3e0eddccc10990f32d1a1b367
+git_commit_count: 1
+---

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

@@ -0,0 +1,164 @@
+schema_version: 1
+object_type: commit_audit_sheet
+versioning:
+  schema_version: 1
+  revision: 3
+release_version: 0.1.2
+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
+rows:
+  - sha: 402275374979b9372c1491072c4e29b642da523f
+    source_ref: git:402275374979b9372c1491072c4e29b642da523f
+    short_sha: "4022753"
+    changed_paths:
+      - README.md
+      - docs/cli.md
+      - docs/debugging.md
+      - repairledger.toml
+      - tests/test_cli.py
+      - tests/test_explain.py
+      - utterplan/cli.py
+      - utterplan/explain.py
+    stats:
+      files_changed: 8
+      insertions: 560
+      deletions: 10
+    inspected: true
+    inspected_paths:
+      - README.md
+      - docs/cli.md
+      - docs/debugging.md
+      - tests/test_cli.py
+      - tests/test_explain.py
+      - utterplan/cli.py
+      - utterplan/explain.py
+    observed_behavior:
+      Added explain CLI command that renders compiled plans as human-readable
+      speech narratives with optional detail mode
+    public_impact: public
+    decision: accepted
+    stale: false
+    evidence_subject: "feat: explain command added"
+    target_entry_key: entry-0001
+    target_entry_id: entry-0001
+    notes: ""
+  - sha: 2c64e291f0e568310afb7ca5e770ef2b691d9452
+    source_ref: git:2c64e291f0e568310afb7ca5e770ef2b691d9452
+    short_sha: 2c64e29
+    changed_paths:
+      - docs/cli.md
+      - docs/consumer-guide.md
+      - docs/phase-a-completion.md
+      - docs/pykokoro-reference.md
+      - spec/utterplan.schema.json
+      - tests/migration/__init__.py
+      - tests/migration/cases.py
+      - tests/migration/goldens/multilingual_preparation.json
+      - tests/migration/goldens/spokenform_numbers.json
+      - tests/migration/goldens/ssmd_break.json
+      - tests/migration/goldens/ssmd_language_detection.json
+      - tests/migration/goldens/ssmd_marker.json
+      - tests/migration/goldens/ssmd_pronunciation.json
+      - tests/migration/test_pykokoro_frontend_parity.py
+      - tests/reference/dump_pykokoro_frontend.py
+      - tests/reference/test_pykokoro_parity.py
+      - tests/test_consumer_contract.py
+      - tests/test_consumer_readiness.py
+      - tests/test_directives.py
+      - tests/test_explain.py
+      - tests/test_pauses.py
+      - utterplan/cli.py
+      - utterplan/directives.py
+      - utterplan/explain.py
+      - utterplan/model.py
+      - utterplan/parsers.py
+      - utterplan/planner.py
+      - utterplan/utterplan.schema.json
+    stats:
+      files_changed: 28
+      insertions: 1119
+      deletions: 153
+    inspected: true
+    inspected_paths:
+      - docs/consumer-guide.md
+      - docs/phase-a-completion.md
+      - docs/pykokoro-reference.md
+      - utterplan/directives.py
+      - utterplan/model.py
+      - utterplan/parsers.py
+      - utterplan/planner.py
+    observed_behavior:
+      Expanded consumer contract with stable renderer input view, improved
+      directive handling, pause policy, and PyKokoro migration parity
+    public_impact: public
+    decision: accepted
+    stale: false
+    evidence_subject: "feat: prepare for use in pykokoro"
+    target_entry_key: entry-0002
+    target_entry_id: entry-0002
+    notes: ""
+  - sha: 66a88b6a7fbe4cf9e0247cfd81675050f5934fea
+    source_ref: git:66a88b6a7fbe4cf9e0247cfd81675050f5934fea
+    short_sha: 66a88b6
+    changed_paths:
+      - .github/workflows/tests.yml
+      - AGENTS.md
+      - README.md
+      - docs/architecture.md
+      - docs/cli.md
+      - docs/format.md
+      - docs/python-api.md
+      - pyproject.toml
+      - spec/schemas/v1.schema.json
+      - spec/utterplan.schema.json
+      - tests/schema_history/README.md
+      - tests/schema_history/v1/basic.json
+      - tests/schema_history/v1/directives.json
+      - tests/schema_history/v1/markers.json
+      - tests/schema_history/v1/multilingual.json
+      - tests/schema_history/v1/parenthetical.json
+      - tests/schema_history/v1/spokenform_offsets.json
+      - tests/schema_history/v1/ssmd_breaks.json
+      - tests/test_cli.py
+      - tests/test_migration_framework.py
+      - tests/test_schema_history.py
+      - tests/test_schema_registry.py
+      - utterplan/__init__.py
+      - utterplan/cli.py
+      - utterplan/exceptions.py
+      - utterplan/format.py
+      - utterplan/migration.py
+      - utterplan/migrations/__init__.py
+      - utterplan/migrations/registry.py
+      - utterplan/model.py
+      - utterplan/schema_registry.py
+      - utterplan/schemas/v1.schema.json
+      - utterplan/utterplan.schema.json
+      - utterplan/versioning.py
+    stats:
+      files_changed: 34
+      insertions: 2755
+      deletions: 28
+    inspected: true
+    inspected_paths:
+      - utterplan/migration.py
+      - utterplan/schema_registry.py
+      - utterplan/schemas/v1.schema.json
+      - tests/schema_history/
+      - tests/test_migration_framework.py
+      - tests/test_schema_history.py
+      - tests/test_schema_registry.py
+    observed_behavior:
+      Added schema versioning with frozen v1 schema, migration framework,
+      registry, and historical fixture coverage
+    public_impact: public
+    decision: accepted
+    stale: false
+    evidence_subject: "feat: versioning schema"
+    target_entry_key: entry-0003
+    target_entry_id: entry-0003
+    notes: ""

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

@@ -0,0 +1,32 @@
+---
+schema_version: 2
+object_type: release_entry
+versioning:
+  schema_version: 1
+  revision: 1
+entry_id: entry-0001
+release_version: 0.1.2
+kind: added
+summary:
+  Added explain CLI command that renders compiled plans as human-readable speech
+  narratives
+status: accepted
+audience: null
+scopes: []
+source_refs:
+  - git:402275374979b9372c1491072c4e29b642da523f
+paths:
+  - utterplan/explain.py
+  - utterplan/cli.py
+  - docs/cli.md
+  - docs/debugging.md
+issues: []
+prs: []
+sources: []
+contributors: []
+breaking: false
+internal: false
+order: 1
+---
+
+The explain command presents prepared wording, render units, languages, resolved pauses, directives, markers, and warnings. The --details flag adds IDs, offsets, provenance, hashes, and plan identity information.

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

@@ -0,0 +1,33 @@
+---
+schema_version: 2
+object_type: release_entry
+versioning:
+  schema_version: 1
+  revision: 1
+entry_id: entry-0002
+release_version: 0.1.2
+kind: changed
+summary:
+  Improved consumer contract with stable renderer input view and directive
+  handling
+status: accepted
+audience: null
+scopes: []
+source_refs:
+  - git:2c64e291f0e568310afb7ca5e770ef2b691d9452
+paths:
+  - utterplan/directives.py
+  - utterplan/model.py
+  - utterplan/parsers.py
+  - utterplan/planner.py
+  - docs/consumer-guide.md
+issues: []
+prs: []
+sources: []
+contributors: []
+breaking: false
+internal: false
+order: 2
+---
+
+Consumers may now rely on documented plan-level fields for renderer input. Directive handling was improved with better pause policy and PyKokoro migration parity. The consumer guide documents the immutability contract for completed plans.

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

@@ -0,0 +1,37 @@
+---
+schema_version: 2
+object_type: release_entry
+versioning:
+  schema_version: 1
+  revision: 1
+entry_id: entry-0003
+release_version: 0.1.2
+kind: added
+summary: Added schema versioning with frozen v1 schema and migration framework
+status: accepted
+audience: null
+scopes: []
+source_refs:
+  - git:66a88b6a7fbe4cf9e0247cfd81675050f5934fea
+paths:
+  - utterplan/migration.py
+  - utterplan/schema_registry.py
+  - utterplan/schemas/v1.schema.json
+  - tests/schema_history/v1/basic.json
+  - tests/schema_history/v1/directives.json
+  - tests/schema_history/v1/markers.json
+  - tests/schema_history/v1/multilingual.json
+  - tests/schema_history/v1/parenthetical.json
+  - tests/schema_history/v1/spokenform_offsets.json
+  - tests/schema_history/v1/ssmd_breaks.json
+  - tests/test_migration_framework.py
+issues: []
+prs: []
+sources: []
+contributors: []
+breaking: false
+internal: false
+order: 3
+---
+
+Schema v1 is frozen and packaged under a versioned schema-history path. UtterPlan can inspect and migrate supported historical plan JSON before constructing the current UtterancePlan. Migration is representation conversion, not replanning. The migrate command supports --check and refuses output overwrite unless --force is supplied.

utterplan-0.1.2/.ledger/releaseledger/data/ledgers/main/releases/0.1.2/release.md

@@ -0,0 +1,27 @@
+---
+schema_version: 2
+object_type: release
+versioning:
+  schema_version: 1
+  revision: 5
+version: 0.1.2
+status: planned
+history_state: curated
+title: null
+released_at: null
+previous_version: 0.1.1
+cancel_reason: null
+superseded_by: null
+changelog_file: null
+boundary_ref: null
+source_refs: []
+source_count: null
+entry_count: 3
+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
+---

utterplan-0.1.2/.ledger/releaseledger/work/0.1.2/audit-decisions.yaml

@@ -0,0 +1,52 @@
+rows:
+  - sha: 402275374979b9372c1491072c4e29b642da523f
+    inspected: true
+    inspected_paths:
+      - README.md
+      - docs/cli.md
+      - docs/debugging.md
+      - tests/test_cli.py
+      - tests/test_explain.py
+      - utterplan/cli.py
+      - utterplan/explain.py
+    observed_behavior: Added explain CLI command that renders compiled plans as human-readable speech narratives with optional detail mode
+    public_impact: public
+    decision: accepted
+    target_entry_key: entry-0001
+    target_entry_id: null
+    notes: ""
+    stale: false
+  - sha: 2c64e291f0e568310afb7ca5e770ef2b691d9452
+    inspected: true
+    inspected_paths:
+      - docs/consumer-guide.md
+      - docs/phase-a-completion.md
+      - docs/pykokoro-reference.md
+      - utterplan/directives.py
+      - utterplan/model.py
+      - utterplan/parsers.py
+      - utterplan/planner.py
+    observed_behavior: Expanded consumer contract with stable renderer input view, improved directive handling, pause policy, and PyKokoro migration parity
+    public_impact: public
+    decision: accepted
+    target_entry_key: entry-0002
+    target_entry_id: null
+    notes: ""
+    stale: false
+  - sha: 66a88b6a7fbe4cf9e0247cfd81675050f5934fea
+    inspected: true
+    inspected_paths:
+      - utterplan/migration.py
+      - utterplan/schema_registry.py
+      - utterplan/schemas/v1.schema.json
+      - tests/schema_history/
+      - tests/test_migration_framework.py
+      - tests/test_schema_history.py
+      - tests/test_schema_registry.py
+    observed_behavior: Added schema versioning with frozen v1 schema, migration framework, registry, and historical fixture coverage
+    public_impact: public
+    decision: accepted
+    target_entry_key: entry-0003
+    target_entry_id: null
+    notes: ""
+    stale: false

utterplan-0.1.2/.ledger/releaseledger/work/0.1.2/audit.yaml

@@ -0,0 +1,128 @@
+schema_version: 1
+object_type: commit_audit_sheet
+versioning:
+  schema_version: 1
+  revision: 1
+release_version: 0.1.2
+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
+rows:
+  - sha: 402275374979b9372c1491072c4e29b642da523f
+    source_ref: git:402275374979b9372c1491072c4e29b642da523f
+    short_sha: "4022753"
+    changed_paths:
+      - README.md
+      - docs/cli.md
+      - docs/debugging.md
+      - repairledger.toml
+      - tests/test_cli.py
+      - tests/test_explain.py
+      - utterplan/cli.py
+      - utterplan/explain.py
+    stats:
+      files_changed: 8
+      insertions: 560
+      deletions: 10
+    inspected: false
+    inspected_paths: []
+    observed_behavior: ""
+    public_impact: unknown
+    decision: needs_review
+    stale: false
+    evidence_subject: "feat: explain command added"
+  - sha: 2c64e291f0e568310afb7ca5e770ef2b691d9452
+    source_ref: git:2c64e291f0e568310afb7ca5e770ef2b691d9452
+    short_sha: 2c64e29
+    changed_paths:
+      - docs/cli.md
+      - docs/consumer-guide.md
+      - docs/phase-a-completion.md
+      - docs/pykokoro-reference.md
+      - spec/utterplan.schema.json
+      - tests/migration/__init__.py
+      - tests/migration/cases.py
+      - tests/migration/goldens/multilingual_preparation.json
+      - tests/migration/goldens/spokenform_numbers.json
+      - tests/migration/goldens/ssmd_break.json
+      - tests/migration/goldens/ssmd_language_detection.json
+      - tests/migration/goldens/ssmd_marker.json
+      - tests/migration/goldens/ssmd_pronunciation.json
+      - tests/migration/test_pykokoro_frontend_parity.py
+      - tests/reference/dump_pykokoro_frontend.py
+      - tests/reference/test_pykokoro_parity.py
+      - tests/test_consumer_contract.py
+      - tests/test_consumer_readiness.py
+      - tests/test_directives.py
+      - tests/test_explain.py
+      - tests/test_pauses.py
+      - utterplan/cli.py
+      - utterplan/directives.py
+      - utterplan/explain.py
+      - utterplan/model.py
+      - utterplan/parsers.py
+      - utterplan/planner.py
+      - utterplan/utterplan.schema.json
+    stats:
+      files_changed: 28
+      insertions: 1119
+      deletions: 153
+    inspected: false
+    inspected_paths: []
+    observed_behavior: ""
+    public_impact: unknown
+    decision: needs_review
+    stale: false
+    evidence_subject: "feat: prepare for use in pykokoro"
+  - sha: 66a88b6a7fbe4cf9e0247cfd81675050f5934fea
+    source_ref: git:66a88b6a7fbe4cf9e0247cfd81675050f5934fea
+    short_sha: 66a88b6
+    changed_paths:
+      - .github/workflows/tests.yml
+      - AGENTS.md
+      - README.md
+      - docs/architecture.md
+      - docs/cli.md
+      - docs/format.md
+      - docs/python-api.md
+      - pyproject.toml
+      - spec/schemas/v1.schema.json
+      - spec/utterplan.schema.json
+      - tests/schema_history/README.md
+      - tests/schema_history/v1/basic.json
+      - tests/schema_history/v1/directives.json
+      - tests/schema_history/v1/markers.json
+      - tests/schema_history/v1/multilingual.json
+      - tests/schema_history/v1/parenthetical.json
+      - tests/schema_history/v1/spokenform_offsets.json
+      - tests/schema_history/v1/ssmd_breaks.json
+      - tests/test_cli.py
+      - tests/test_migration_framework.py
+      - tests/test_schema_history.py
+      - tests/test_schema_registry.py
+      - utterplan/__init__.py
+      - utterplan/cli.py
+      - utterplan/exceptions.py
+      - utterplan/format.py
+      - utterplan/migration.py
+      - utterplan/migrations/__init__.py
+      - utterplan/migrations/registry.py
+      - utterplan/model.py
+      - utterplan/schema_registry.py
+      - utterplan/schemas/v1.schema.json
+      - utterplan/utterplan.schema.json
+      - utterplan/versioning.py
+    stats:
+      files_changed: 34
+      insertions: 2755
+      deletions: 28
+    inspected: false
+    inspected_paths: []
+    observed_behavior: ""
+    public_impact: unknown
+    decision: needs_review
+    stale: false
+    evidence_subject: "feat: versioning schema"

utterplan-0.1.2/.ledger/releaseledger/work/0.1.2/entries.yaml

@@ -0,0 +1,56 @@
+entries:
+  - kind: added
+    summary: Added explain CLI command that renders compiled plans as human-readable speech narratives
+    body: >
+      The explain command presents prepared wording, render units, languages,
+      resolved pauses, directives, markers, and warnings. The --details flag
+      adds IDs, offsets, provenance, hashes, and plan identity information.
+    status: accepted
+    source_refs:
+      - git:402275374979b9372c1491072c4e29b642da523f
+    paths:
+      - utterplan/explain.py
+      - utterplan/cli.py
+      - docs/cli.md
+      - docs/debugging.md
+
+  - kind: changed
+    summary: Improved consumer contract with stable renderer input view and directive handling
+    body: >
+      Consumers may now rely on documented plan-level fields for renderer input.
+      Directive handling was improved with better pause policy and PyKokoro
+      migration parity. The consumer guide documents the immutability contract
+      for completed plans.
+    status: accepted
+    source_refs:
+      - git:2c64e291f0e568310afb7ca5e770ef2b691d9452
+    paths:
+      - utterplan/directives.py
+      - utterplan/model.py
+      - utterplan/parsers.py
+      - utterplan/planner.py
+      - docs/consumer-guide.md
+
+  - kind: added
+    summary: Added schema versioning with frozen v1 schema and migration framework
+    body: >
+      Schema v1 is frozen and packaged under a versioned schema-history path.
+      UtterPlan can inspect and migrate supported historical plan JSON before
+      constructing the current UtterancePlan. Migration is representation
+      conversion, not replanning. The migrate command supports --check and
+      refuses output overwrite unless --force is supplied.
+    status: accepted
+    source_refs:
+      - git:66a88b6a7fbe4cf9e0247cfd81675050f5934fea
+    paths:
+      - utterplan/migration.py
+      - utterplan/schema_registry.py
+      - utterplan/schemas/v1.schema.json
+      - tests/schema_history/v1/basic.json
+      - tests/schema_history/v1/directives.json
+      - tests/schema_history/v1/markers.json
+      - tests/schema_history/v1/multilingual.json
+      - tests/schema_history/v1/parenthetical.json
+      - tests/schema_history/v1/spokenform_offsets.json
+      - tests/schema_history/v1/ssmd_breaks.json
+      - tests/test_migration_framework.py