docs: define Swang language and verified lifting roadmap

[PhysShell]

Summary

Documents Swang as Griff's proposed deterministic musical authoring language and adds the S16 roadmap for verified MIDI/Guitar Pro lifting into optimized executable programs.

Closes no implementation work. This is an architecture and delivery-contract PR linked to #108.

What changed

• adds ADR-0028: Swang is a frontend over canonical Score, never a competing musical model;
• adds proposed S16 with phased delivery from exact score text and bounded pattern algebra through verified lifting, optimization, fractal recognition, and script-writing generators;
• indexes ADR-0028 in the ADR table.

Key decisions proposed

• three language levels: high-level recipes, pattern algebra, and exact residual/patch syntax;
• deterministic, versioned, bounded compilation with inspectable expansion;
• fractalize operates on structure before rhythm, pitch, technique, and fretboard realization;
• MIDI/GP lifting is program synthesis, not a note-per-line dump;
• every lifted program is re-executed and compared against the canonical source Score;
• lossless, structural, and generative lifting modes remain explicit;
• unmatched musical detail is preserved through exact residual patches;
• program selection uses a versioned, inspectable description-cost objective;
• generators may later emit and mutate Swang ASTs;
• generic discrete-signal reuse is permitted only below the music-specific mapping boundary;
• S15 TonalContext remains closed/frozen unless separately reopened by its own acceptance contract.

First milestone

The first bounded milestone combines:

1. exact canonical score text and semantic round-trip;
2. pure bounded Pattern Core;
3. pattern-to-RhythmTemplate lowering through the existing S6 seam;
4. minimal executable .swg scripts;
5. lifting v0 for repeats, motifs, transposition, changed endings, exact residuals, and execute-to-verify reporting.

Fractal lifting and LLM clients are explicitly later phases. Humanity may survive the restraint.

Validation

• docs-only branch created from current main;
• branch is 3 commits ahead and 0 behind;
• diff contains only the two new documents and one ADR-index row;
• no production code or generation behavior changed;
• no test suite run because the change is documentation-only.

Review focus

• whether S16 is the correct append-only stage owner;
• whether the compile/lift boundary preserves canonical Score correctly;
• whether lifting modes and residual semantics are strict enough;
• whether the first implementation milestone is small enough to avoid a compiler-shaped sinkhole;
• whether any term should be renamed before the language/file extension becomes durable.

Related: #108

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 3fbfe64e-cde9-4171-814e-b92792b36187

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch agent/document-swang-language-and-lift

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[PhysShell]

Superseded by #111, which carries the same ADR + S16 scope plus the SPEC/README/index wiring. The Swang ADR will take the next free number after #112 lands (ADR-0028 is claimed by the theme-tokens ADR already implemented there); #111 is being reworked to the agreed pattern-first plan. See #108 for the design discussion.