Skip to content

Add informational story annotation to the scene DSL#8

Merged
jamiesun merged 1 commit into
mainfrom
scene-story-annotation
Jul 19, 2026
Merged

Add informational story annotation to the scene DSL#8
jamiesun merged 1 commit into
mainfrom
scene-story-annotation

Conversation

@jamiesun

Copy link
Copy Markdown
Contributor

What

Adds an optional story field to the scene document: a freeform narrative description (theme, mood, dramatic intent) that downstream agents can use to review the compiled music against its intended story.

title: Forest Theme
story: >-
  Calm nocturnal forest ambience for the exploration loop — soft, unhurried,
  no threat; the player should feel safe wandering under the canopy.

Design

  • Informational only, like title — zero compile semantics; a scene with story produces byte-identical MIDI to the same scene without it.
  • Echoed into meta.json (single-scene output and suite manifest) so the compiled artifact is self-describing for agent review pipelines.
  • Does not reopen the rejected semantic Story/character field (character: {regret: 0.9}, roadmap): that ruling concerned fields with musical meaning but no deterministic compile semantics. This is a pure annotation; a boundary note in docs/roadmap.md records the distinction.

Protocol extension gates (scene-protocol.md)

  • ✅ Optional; absence compiles byte-identically to the world before the field — golden SMF test unchanged even though forest.yaml now carries a story
  • ✅ Happy-path E2E: story_is_informational_and_never_affects_midi_bytes (validate + with/without byte comparison)
  • ✅ Failure path: validate_rejects_non_string_story_with_location
  • ✅ meta.json assertions in build_full_chain_scene_to_ogg; schema output assertion
  • ✅ Acceptance matrix row updated in docs/roadmap.md
  • ✅ Docs: scene-protocol table, skill SKILL.md/reference.md, README example

Validation

make check fully green: cargo fmt --check, clippy -D warnings, all 74 E2E tests.

Each scene can now carry a freeform story field describing its theme,
mood and dramatic intent. Like title, it is informational only — it
never affects compiled output (guarded by a byte-identity E2E test) —
and is echoed into meta.json so downstream review agents can audit the
music against its intended story.

Per the scene-protocol extension gates: optional with an absent-equals-
before default, happy-path E2E + failure-path tests, docs and the
acceptance matrix updated in the same change. The roadmap's rejection
of semantic story/character fields is untouched; a boundary note marks
this as a zero-semantics annotation.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
@jamiesun
jamiesun merged commit 5f4a14c into main Jul 19, 2026
1 check failed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant