ADR-022 Amendments to Existing ADRs
Companion document to ADR-022 (Device Discovery, Bindings & Multi-Protocol Routing).
Specifies all amendments and modifications that ADR-022 makes to existing Architecture Decision Records. Each amendment is independently scoped, reversible, and cross-references the originating GitHub issue.
Amendment 1: ADR-013 (LLM Canvas)
A1.1: Binding-Topology Artifact (Phase 3A)
Change: Rename device-topology artifact to binding-topology. Migrate data model from hierarchical (device → mode → mapping) to three-column graph view (port → binding → mapping).
Rationale: Device topology describes physical hardware structure. Binding topology describes the logical relationship between discovered ports, established bindings, and configured mappings—a more useful semantic for LLM reasoning about connectivity gaps.
Data Model:
Column 1: Discovered Ports (protocol, name, state)
Column 2: Bindings (alias, matcher, health, event rate)
Column 3: Mappings (trigger, action, conditions)
Data Sources:
- Primary:
conductor_list_discovered_ports(MCP tool) - Secondary: Binding health from
conductor_get_binding_health(new Phase 2 MCP tool) - Tertiary: Mapping detail from
conductor_list_mappings
Scope: Phase 3A (LLM Canvas Phase 2 implementation)
GitHub Issue: #624
Effort Impact: +2–3 hours (artifact schema design, example generation, prompt engineering)
A1.2: Discovery-Overview Artifact Type (Phase 3A)
Change: Add lightweight discovery-overview artifact type for LLM Canvas Phase 1 (discovery & binding design workflow).
Purpose: Complements the detailed binding-topology. Provides fast visual summary of port discovery state without mapping detail.
Content:
- Discovered port list with bound/unbound badges
- Protocol icons (🎹 MIDI, 🎮 HID, 📡 OSC, 💡 SYSEX)
- Count summaries (e.g., "5 bound, 2 unbound")
- "Create Binding" action buttons for unbound ports
- Device identity hints (vendor, port name)
Scope: Phase 3A (scoped within artifact generation, not canvas workflow)
GitHub Issue: #624
Effort Impact: +1–2 hours (artifact template, aggregation logic)
Total A1 Impact: Phase 3A effort +3–5 hours
Amendment 2: ADR-017 (Unified Mapping Experience)
A2.1: MIDI Learn Source Annotation (Phase 1B)
Change: Extend D1 (MIDI Learn Mode) with optional source annotation field.
Feature: After MIDI event capture, user sees prompt: "What physical device produced this? (optional)". Text input field, stored as source_annotation on LearnCaptureResult type.
Rationale: Captures bridge transparency concern raised in #605. When learning from multi-device setups, knowing the source device aids LLM reasoning about context and binding design.
Implementation:
LearnCaptureResultgainssource_annotation: Option<String>fieldMidiLearnRefinement.svelteadds text input in post-capture refinement card- Stored in
conductor.dbaudit log for traceability - Exposed via
conductor_get_learn_historyMCP tool
Scope: Phase 1B (MIDI Learn post-capture refinement)
GitHub Issue: #605
Effort Impact: +1–2 hours
A2.2: Events-to-Binding Bridge (Phase 1B)
Change: Extend D6 (Events-to-Mapping Bridge) to Events-to-Binding Bridge. Replace device-scoped event filtering with binding-scoped.
Feature:
- EventStreamPanel shows events with binding context (if bound) or unbound status
- Unbound ports display "Create Binding" action button
- RefinementCard gains new "Source Binding" section showing source port details (protocol, vendor, port name)
Rationale: Unifies learning flow across multi-device scenarios. Source port becomes first-class concept in MIDI Learn UI.
Implementation:
EventRow.svelterefactored: device_id → (device_id + binding_alias)- New
SourceBindingSection.sveltecomponent EventFilter.sveltegains binding multi-select option- Event emit payloads include binding_alias + device_identity
Scope: Phase 1B (Events-to-Mapping Bridge refinement)
GitHub Issue: #605
Effort Impact: +1–2 hours
A2.3: Learn Mode Skill Rename Ratification (Phase 1B)
Change: Ratify D7 (Learn Mode Skill Naming). Skill renamed from conductor-midi-learn to conductor-learn.
Rationale: New learn mode supports HID and OSC triggers, not just MIDI. Existing name is domain-specific; new name is protocol-agnostic. Aligns with multi-protocol routing goal of ADR-022.
Implementation: Rename in skills/conductor-learn/SKILL.md and all references. Update conductor-skills tool output.
Scope: Phase 1B (additive change, no functional impact)
GitHub Issue: #606
Effort Impact: Minimal (<15 minutes, documentation only)
Total A2 Impact: Phase 1B effort +2–4 hours
Amendment 3: ADR-018 (Knowledge Layer)
A3.1: Binding Schema in L1 Core Reference (Phase 1A)
Change: Extend L1 (Core Reference knowledge chunk) to include binding schema documentation (~1,250 tokens).
Content:
- Three-layer model explanation (discovery → binding → mapping)
[[bindings]]TOML syntax with full example- Matcher types (ByPortName, ByDeviceIdentity, BySerialNumber, ByProto)
- Binding properties (alias, device_filter, enabled, channel_scope)
- Channel scope semantics (AllChannels vs. specific channel ranges)
- Common interaction patterns (monophonic, polyphonic, layer switching)
Rationale: Binding is new first-class concept. Knowledge layer must document it at core level for LLM grounding.
Scope: Phase 1A (knowledge chunk assembly)
GitHub Issue: #646
Effort Impact: +1 hour (writing, validation)
A3.2: Device Profiles Specify Binding-Relevant Content (Phase 1A & ongoing)
Change: Device Profile L2 chunks now specify binding-relevant metadata: port naming conventions, note/CC ranges, LED protocols, suggested matcher strategies.
Content per profile (Novation Launchpad example):
- Port naming: "Launchpad Pro [1]", "Launchpad Pro [2]"
- Note range: 36–99 (grid), CC range: 104–119 (buttons)
- LED protocols: RGB (3-byte SysEx)
- Suggested matchers: ByPortName (high confidence), ByDeviceIdentity (fallback)
Profiles affected: NI Maschine Mikro MK3, Novation Launchpad Pro/Mini, Akai APC40 mk2, KORG nanoKONTROL2, Arturia Beatstep, Behringer FCB1010
Scope: Phase 1A (profile updates) + ongoing L2 curation
GitHub Issue: #650
Effort Impact: +2–3 hours (Phase 1A only; ongoing is operational, not effort-tracked)
A3.3: Community Profiles L3 Content Clarification (Phase ongoing)
Change: Clarify that L3 (Community Profiles) primary content type is binding configurations, not generic device profiles.
Expected L3 chunks: User-submitted binding profiles for specific hardware combinations (e.g., "Launchpad Pro + Mikro Hybrid Setup", "Behringer FCB1010 + Sustain Pedal Chain").
Rationale: Community profiles shine when grounded in real-world use cases. Binding-scoped profiles are more actionable for LLM assistance than generic device metadata.
Scope: Phase ongoing (community contribution guidelines update)
GitHub Issue: #654
Effort Impact: Negligible (documentation clarification only)
Total A3 Impact: Phase 1A +3–4 hours; later phases minimal
Amendment 4: ADR-019 (Unified Workspace Filtering)
A4.1: DeviceStatusPills → BindingPills Rename (Phase 2)
Change: Rename component DeviceStatusPills to BindingPills. Extend to show binding-level state, not device-level.
New Features:
- +N Unbound badge: "Unbound (3)" clickable pill → Connections view showing unbound sources
- Protocol icons per binding (🎹 MIDI, 🎮 HID, 📡 OSC)
- Health indicator (green/yellow/red) from binding health metric
- Click binding pill → Signal Flow filtered to that binding
Rationale: Workspace filtering should align with logical binding abstraction, not physical device abstraction. Users think in terms of "my Launchpad binding" not "my Launchpad device".
Component Location: src/lib/components/workspace/BindingPills.svelte (replaces DeviceStatusPills)
Scope: Phase 2 (Event Stream view update)
GitHub Issue: #645
Effort Impact: +1.5–2 hours
A4.2: Unmapped → Unbound Sources Concept (Phase 2)
Change: Distinguish two states: Unbound (port has no binding) vs. Unmapped (port is bound but no matching mapping rules).
New Filter Chip: "Unbound Sources" (separate from "Unmapped Events"). When active, shows events from ports without bindings.
New Metrics:
unboundEventRate: Events/sec from ports with no bindingUnboundSourcesGroup: New Signal Flow group below bound groups, dashed border, 50% opacity
Scope: Phase 2 (Signal Flow filtering, metrics)
GitHub Issue: #645
Effort Impact: +1–2 hours (metrics aggregation, UI components)
Total A4 Impact: Phase 2 effort +2.5–4 hours
Amendment 5: ADR-020 (V3 Signal Flow)
A5.1: DeviceGroup Binding Scope (Phase 2)
Change: DeviceGroup reframed as BindingGroup keyed by binding alias. Update DeviceHeader to show binding-specific metadata.
New DeviceHeader (per binding group):
- Binding alias (large, bold)
- Protocol badge (🎹/🎮/📡)
- Interaction pattern label (e.g., "Monophonic", "Grid", "Fader Bank")
- Health indicator (green/yellow/red) from binding health metric
- Binding enable/disable toggle
- Edit binding button → Connections view
Rationale: Signal Flow is mapping-centric; mappings belong to bindings, not devices. Binding alias provides user-friendly grouping.
Component Updates: Rename DeviceGroup.svelte → BindingGroup.svelte. Extend DeviceHeader.svelte with binding fields.
Scope: Phase 2 (Signal Flow architecture update)
GitHub Issue: #667
Effort Impact: +2–3 hours
A5.2: UnboundSourcesGroup Component (Phase 2)
Change: Add new Signal Flow group type for unbound sources. Appears below all bound BindingGroups.
Visual Style:
- Dashed border (not solid)
- 50% opacity background (visual de-emphasis)
- Title: "Unbound Sources (3)" with count badge
Content (per unbound port):
- Port name / vendor ID
- Protocol icon (🎹/🎮/📡)
- Event rate (e.g., "12 events/sec")
- Event type distribution pie chart (Note vs. CC vs. Buttons)
- "+Bind" call-to-action button → Bindings.svelte (create new binding)
Component: New UnboundSourcesGroup.svelte with UnboundSourceRow.svelte subcomponent
Scope: Phase 2 (Signal Flow view expansion)
GitHub Issue: #667
Effort Impact: +2–3 hours
Total A5 Impact: Phase 2 effort +4–6 hours
Summary: Amendment Impact Matrix
| Amendment | Affected ADR | Phase | Effort Delta | GitHub Issue | Type |
|---|---|---|---|---|---|
| A1.1 | ADR-013 | 3A | +2–3h | #624 | Artifact design |
| A1.2 | ADR-013 | 3A | +1–2h | #624 | Artifact type |
| A2.1 | ADR-017 | 1B | +1–2h | #605 | Learn feature |
| A2.2 | ADR-017 | 1B | +1–2h | #605 | Learn feature |
| A2.3 | ADR-017 | 1B | <15m | #606 | Documentation |
| A3.1 | ADR-018 | 1A | +1h | #646 | Knowledge chunk |
| A3.2 | ADR-018 | 1A | +2–3h | #650 | Profile updates |
| A3.3 | ADR-018 | ongoing | Negligible | #654 | Guidelines |
| A4.1 | ADR-019 | 2 | +1.5–2h | #645 | Component rename |
| A4.2 | ADR-019 | 2 | +1–2h | #645 | Metrics & filtering |
| A5.1 | ADR-020 | 2 | +2–3h | #667 | Signal Flow |
| A5.2 | ADR-020 | 2 | +2–3h | #667 | Signal Flow |
Cumulative Effort Impact:
- Phase 1A: +3–4 hours
- Phase 1B: +2–4 hours
- Phase 2: +7–11 hours
- Phase 3A: +3–5 hours
- Total: +15–24 hours (7–12% scope expansion over ADR-022 baseline)
Cross-Cutting Concerns
Component Renames
Renames are internal refactorings (DeviceStatusPills → BindingPills, DeviceGroup → BindingGroup). No breaking changes to Tauri commands, public APIs, or config format. All renames are tracked in CHANGELOG.md under ADR-022.
Additive Nature
All amendments are additive—no existing features are removed or fundamentally redesigned. Binding concept extends (not replaces) device management. Source annotation is optional. Unbound state is new, unmapped state preserved.
Reversibility
Each amendment is independently reversible via git revert. If binding-scoped Signal Flow proves problematic, revert A5.1–A5.2 and restore device-scoped grouping without cascading failures.
Testing Strategy
Phase boundaries trigger LLM Council verification (verify MCP tool with rubric focus "architecture" for layout amendments, "correctness" for schema amendments). Confidence threshold 0.7. If confidence < 0.7 or blocking issues present, fix before phase progression.
Documentation Alignment
All amendments are annotated in source design documents:
docs/gui-v2/implementation-spec.md: Phase mapping updatedCHANGELOG.md: All amendments logged with GitHub links- Component docstrings: Semantic updates (device → binding terminology)
Version: ADR-022 v1.0 Date: 2026-03-20 Status: Approved Companion: ADR-022 (Device Discovery, Bindings & Multi-Protocol Routing)