docs: add S15 tonal roadmap and map symbolic-harmony research - #103
Conversation
📝 WalkthroughWalkthroughThe PR updates roadmap governance and stage documentation for symbolic harmony, global path optimization, preview tooling, human feedback, neural-assistance boundaries, and structural evolution experiments across stages S6–S15. ChangesRoadmap, harmony, and evolution planning
Estimated code review effort: 2 (Simple) | ~15 minutes 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
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. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 9
🧹 Nitpick comments (1)
docs/stages/S15-tonal-context-and-harmonic-control.md (1)
3-7: 🗄️ Data Integrity & Integration | 🔵 Trivial | ⚡ Quick winDisambiguate the S6 dependency from the downstream feed.
S15 currently both “Depends on” S6 and “Feeds” S6, which reads as a circular implementation dependency. Clarify that Phase 0/1 consume the existing S6 baseline, while only later S15 phases feed future S6 generation.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/stages/S15-tonal-context-and-harmonic-control.md` around lines 3 - 7, Update the S15 dependency metadata to distinguish phases: state that Phase 0/1 consume the existing S6 rule-generator baseline, and clarify that only later S15 phases feed future S6 generation. Remove the ambiguous direct “Depends on: S6” and “Feeds: S6 generation” wording while preserving the other dependency relationships.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/stages/S12-neural-assistance.md`:
- Around line 40-45: Make the harmonic assistance criterion in the Acceptance
criteria section measurable by specifying the labelled evaluation-set scope,
baseline comparison metrics, calibrated-uncertainty target, and explicit
thresholds or conditions for both beating and complementing the S15 symbolic
baseline.
- Around line 32-38: The S12 preconditions reference accepted S15 fixtures
without explicitly requiring the S15 work that produces them. Update the
Preconditions hard gate to name the required S15 phases for the labelled
controls and harmonic fixture DSL, or clearly distinguish the currently
available S15 estimator from future fixtures while preserving the comparison and
uncertainty/abstention requirements.
In `@docs/stages/S6-rule-generator-v0.md`:
- Around line 23-27: Update the S6 stage status and acceptance-criteria wording
so density and syncopation corpus gates are not presented as both unresolved
follow-ups and satisfied gates. Either mark S6 as in progress until those gates
are met, tested, and documented, or explicitly classify them as non-gating
follow-ups while preserving accurate acceptance criteria.
In `@docs/stages/S7-graph-layer.md`:
- Around line 84-92: Define the deterministic k-best contract in Slice C:
specify the path representation, diversity distance and threshold, and whether
filtering occurs before or after global ranking. Record these as resolved
semantics or an explicit open question, and ensure the contract preserves
reproducible top-k global selection rather than allowing path clones.
- Around line 59-63: Clarify in the S7 scoring specification that the displayed
expression is a utility maximized by the ranking logic in core/src/scoring.rs,
or explicitly define the negated form if it is retained as a minimized cost.
Also document the neutral value and behavior used for harmonic_fit when optional
S15 harmonic state is unavailable or not yet calibrated.
- Around line 100-110: Update the acceptance criteria section to name the
quality score, fixture or corpus, and comparison threshold used to show
recombined chains outperform S6. Define a measurable global-arc rule for
multi-bar outputs, including the fixture and threshold for detecting excessive
repeated techniques. Revise the determinism criterion to allow tied optima while
requiring the documented fixed tie-break to select consistently, and specify how
k-best diversity is measured.
In `@docs/stages/S8-preview-app.md`:
- Around line 63-65: Update the Candidate/provenance inspector requirements in
the S8 preview-app document to include the complete S9 feedback identity
contract: candidate stable IDs plus generation and session_id. Specify the
source of generation and session_id, and require the inspector/view model to
carry both values through to feedback persistence.
In `@docs/stages/S9-feedback-layer.md`:
- Around line 39-45: Update the Phase 1 preference reranking EMA specification
around the approve/sign update to define verdict mappings: document the exact
positive magnitude for favorite, distinguish like and dislike behavior, and
explicitly state that skip produces no weight update. Keep the existing EMA
formula and normalization requirements unchanged.
- Around line 93-105: Update the reproducibility acceptance criterion to include
evolution decisions—user-selected parents and operator/mutation choices—as
replay inputs, or explicitly require them to be deterministic outputs of the
seed. Ensure the contract guarantees identical documented inputs reproduce the
same population and lineage.
---
Nitpick comments:
In `@docs/stages/S15-tonal-context-and-harmonic-control.md`:
- Around line 3-7: Update the S15 dependency metadata to distinguish phases:
state that Phase 0/1 consume the existing S6 rule-generator baseline, and
clarify that only later S15 phases feed future S6 generation. Remove the
ambiguous direct “Depends on: S6” and “Feeds: S6 generation” wording while
preserving the other dependency relationships.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro Plus
Run ID: bfc117e6-bb8a-4112-91ff-cd138273d5b2
📒 Files selected for processing (9)
docs/audit/2026-05-stage-label-reconciliation.mddocs/audit/2026-07-symbolic-harmony-and-evolution-research.mddocs/stages/S12-neural-assistance.mddocs/stages/S13-complementary-part-generation.mddocs/stages/S15-tonal-context-and-harmonic-control.mddocs/stages/S6-rule-generator-v0.mddocs/stages/S7-graph-layer.mddocs/stages/S8-preview-app.mddocs/stages/S9-feedback-layer.md
| ## Preconditions (hard gate) | ||
|
|
||
| - Corpus ≥ ~100 phrases; working S6 baseline; S9 feedback integration. | ||
| - Not started before all three hold (glossary §17.5). | ||
| - Any harmonic neural proposal must also compare against the accepted S15 | ||
| symbolic estimator/fixtures and preserve uncertainty/abstention rather than | ||
| emit one unquestioned label. |
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🟠 Major | 🏗️ Heavy lift
Make the S15 prerequisite explicit.
S15’s labelled controls and harmonic fixture DSL are future Phase 3/4 work, but this hard gate requires “accepted S15 ... fixtures” without adding the required S15 phase to S12’s prerequisites. Require the relevant S15 phases explicitly, or distinguish the currently available estimator from future fixtures.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/stages/S12-neural-assistance.md` around lines 32 - 38, The S12
preconditions reference accepted S15 fixtures without explicitly requiring the
S15 work that produces them. Update the Preconditions hard gate to name the
required S15 phases for the labelled controls and harmonic fixture DSL, or
clearly distinguish the currently available S15 estimator from future fixtures
while preserving the comparison and uncertainty/abstention requirements.
| ## Acceptance criteria | ||
|
|
||
| - Neural suggestions beat S6/S7 on the quality score in a blind comparison. | ||
| - Deterministic given a fixed seed and model checkpoint. | ||
| - Harmonic assistance, when attempted, beats or complements the S15 symbolic | ||
| baseline on a labelled test set and reports calibrated uncertainty. |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟠 Major | 🏗️ Heavy lift
Make harmonic acceptance measurable.
“Beats or complements” the S15 baseline is not a testable acceptance criterion. Define the labelled evaluation set, comparison metrics, calibration target, and what qualifies as a complementary result.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/stages/S12-neural-assistance.md` around lines 40 - 45, Make the harmonic
assistance criterion in the Acceptance criteria section measurable by specifying
the labelled evaluation-set scope, baseline comparison metrics,
calibrated-uncertainty target, and explicit thresholds or conditions for both
beating and complementing the S15 symbolic baseline.
| > Remaining follow-ups from the list below: anchor preservation, the string/fret | ||
| > playability filter, and the density/syncopation corpus gates. Cadence-aware | ||
| > endings are no longer owned as an unscoped S6 patch: they move to **S15 Phase | ||
| > 6**, after explicit tonal context, scope/confidence calibration, and an | ||
| > abstention path exist. |
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick win
Do not mark S6 done while its acceptance gates remain open.
Density and syncopation are listed as remaining corpus gates here, but they remain acceptance criteria below. Either move them into explicitly non-gating follow-ups or change the status to in progress; the reconciliation audit requires closed stages to have met, tested, and documented acceptance criteria.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/stages/S6-rule-generator-v0.md` around lines 23 - 27, Update the S6
stage status and acceptance-criteria wording so density and syncopation corpus
gates are not presented as both unresolved follow-ups and satisfied gates.
Either mark S6 as in progress until those gates are met, tested, and documented,
or explicitly classify them as non-gating follow-ups while preserving accurate
acceptance criteria.
| `EnergyState`, rhythmic similarity to part A, and optional S15 harmonic state | ||
| once that contract is calibrated. | ||
| - Cost function (inspectable, the same weights S9 later tunes): | ||
| `harmonic_fit + rhythm_complement + style_fit + playability + phrase_continuity | ||
| − mud_penalty − repetition_penalty − fret_jump_penalty`. |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟠 Major | ⚡ Quick win
Define whether this expression is a score or a minimised cost.
The formula is named a cost, but positive fit terms improve the result; meanwhile core/src/scoring.rs ranks higher aggregates first. State explicitly whether S7 maximises this utility or minimises its negation. Also define the neutral/omitted behavior for harmonic_fit before S15 is calibrated.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/stages/S7-graph-layer.md` around lines 59 - 63, Clarify in the S7
scoring specification that the displayed expression is a utility maximized by
the ranking logic in core/src/scoring.rs, or explicitly define the negated form
if it is retained as a minimized cost. Also document the neutral value and
behavior used for harmonic_fit when optional S15 harmonic state is unavailable
or not yet calibrated.
| ### Slice C — deterministic k-best alternatives | ||
|
|
||
| Return several ranked global paths with: | ||
|
|
||
| - fixed tie-breaking; | ||
| - complete total/local/transition explanations; | ||
| - an explicit diversity rule so alternatives are not path clones; | ||
| - stable provenance for S8 display and S9 feedback. | ||
|
|
There was a problem hiding this comment.
🎯 Functional Correctness | 🟠 Major | 🏗️ Heavy lift
Define the diversity rule and k-best selection semantics.
“Explicit diversity rule” is currently only a placeholder: specify the path representation, distance threshold, and whether diversity filtering occurs before or after ranking. Add this as a resolved contract or an explicit open question; otherwise “deterministic k-best” is not reproducible and may not actually return the top-k globally ranked paths.
Also applies to: 111-118
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/stages/S7-graph-layer.md` around lines 84 - 92, Define the deterministic
k-best contract in Slice C: specify the path representation, diversity distance
and threshold, and whether filtering occurs before or after global ranking.
Record these as resolved semantics or an explicit open question, and ensure the
contract preserves reproducible top-k global selection rather than allowing path
clones.
| ## Acceptance criteria | ||
|
|
||
| - Recombined chains beat S6 single-strategy output on a defined quality score. | ||
| - Deterministic for a fixed cost function (Viterbi optimum is unique; ties break | ||
| by a fixed documented rule). | ||
| - Multi-bar output shows a global arc (e.g. no 4 identical-technique bars in a | ||
| row), not a chain of locally-best fragments. | ||
| - Every selected path exposes local and transition-cost explanations. | ||
| - k-best alternatives are deterministic and measurably distinct under the | ||
| documented diversity rule. | ||
|
|
There was a problem hiding this comment.
🎯 Functional Correctness | 🟠 Major | 🏗️ Heavy lift
Make the acceptance criteria executable.
The criteria need a named quality score, fixture/corpus, comparison threshold, and measurable global-arc rule. Also, “the Viterbi optimum is unique” conflicts with the documented fixed tie-break behavior: tied optima should be allowed as long as selection is deterministic.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/stages/S7-graph-layer.md` around lines 100 - 110, Update the acceptance
criteria section to name the quality score, fixture or corpus, and comparison
threshold used to show recombined chains outperform S6. Define a measurable
global-arc rule for multi-bar outputs, including the fixture and threshold for
detecting excessive repeated techniques. Revise the determinism criterion to
allow tied optima while requiring the documented fixed tie-break to select
consistently, and specify how k-best diversity is measured.
| - [ ] **Candidate/provenance inspector** — candidate scores, novelty, register, | ||
| playability, tonal hypotheses, S7 path/transition explanations, and stable | ||
| ids sufficient for S9 feedback. |
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick win
Document the complete S9 feedback identity contract.
Stable candidate IDs alone are not sufficient for the S9 feedback event: docs/stages/S9-feedback-layer.md:28-33 also requires generation and session_id. Specify where those values come from and ensure the inspector/view model carries them so feedback provenance can be persisted correctly.
Also applies to: 130-133
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/stages/S8-preview-app.md` around lines 63 - 65, Update the
Candidate/provenance inspector requirements in the S8 preview-app document to
include the complete S9 feedback identity contract: candidate stable IDs plus
generation and session_id. Specify the source of generation and session_id, and
require the inspector/view model to carry both values through to feedback
persistence.
| ### Phase 1 — preference reranking | ||
|
|
||
| - Like/dislike/favorite → update feature weights. | ||
| - Baseline EMA update: `w_i ← (1-α)·w_i + α·sign(approve)·feature_i_norm`, | ||
| `α ≈ 0.1`, weights normalized on the L1 simplex. | ||
| - Explainable rerank by similarity / features / tags. | ||
| - No gradient descent / RL before S10. |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟠 Major | ⚡ Quick win
Define how each feedback verdict updates the EMA.
The documented inputs include like, dislike, favorite, and skip, but sign(approve) only defines a binary update. Specify the mapping and magnitude for favorite, and explicitly state that skip is a no-op; otherwise implementations can diverge while still appearing to satisfy the contract.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/stages/S9-feedback-layer.md` around lines 39 - 45, Update the Phase 1
preference reranking EMA specification around the approve/sign update to define
verdict mappings: document the exact positive magnitude for favorite,
distinguish like and dislike behavior, and explicitly state that skip produces
no weight update. Keep the existing EMA formula and normalization requirements
unchanged.
| ## Acceptance criteria | ||
|
|
||
| - Ratings measurably shift subsequent ranking toward liked features | ||
| (deterministic test with synthetic ratings). | ||
| - The profile is inspectable and resettable. | ||
| - Feedback events retain stable candidate/session provenance. | ||
| - Evolution operators preserve structural validity and pass the normal generator | ||
| validators. | ||
| - Fixed inputs, feedback sequence, and seed reproduce the same population and | ||
| lineage. | ||
| - Diversity/collapse metrics are reported before Evolution Lab is considered for | ||
| product use. | ||
|
|
There was a problem hiding this comment.
🎯 Functional Correctness | 🟠 Major | ⚡ Quick win
Include evolution decisions in the reproducibility inputs.
Phase 2 includes user-selected parents and operator/mutation choices, but the acceptance criterion only fixes inputs, feedback, and seed. Add those decisions to the replay contract, or define them as deterministic outputs of the seed; otherwise identical documented inputs may produce different populations and lineage.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/stages/S9-feedback-layer.md` around lines 93 - 105, Update the
reproducibility acceptance criterion to include evolution
decisions—user-selected parents and operator/mutation choices—as replay inputs,
or explicitly require them to be deterministic outputs of the seed. Ensure the
contract guarantees identical documented inputs reproduce the same population
and lineage.
1 participant
Summary
Adds the append-only S15: Tonal context and harmonic control stage and maps the recent symbolic-harmony / interactive-evolution research onto the existing roadmap instead of inventing competing ownership.
New docs
docs/stages/S15-tonal-context-and-harmonic-control.mddocs/audit/2026-07-symbolic-harmony-and-evolution-research.mdekzhang/harmony,napulen/romanyh,AugmentedNet,harmalysis,perfect-shuffle-music,composing.studio, andcrepeas architectural inputs;Existing stage updates
Why
The research converges on one product line:
The docs now assign each part once:
Impact
Documentation only. No production code, schema, generation behaviour, dependency, or acceptance status changes.
Validation
main: 9 documentation files only, 0 code files.af26206; Phase 2 is documented as not started.Summary by CodeRabbit