# requirement_nodes

id: S-02
title: Low Cost Hardware
priority: high
status: idea
node_type: sub_requirement
parent_id: FUNC.HW
test_status: not_written
created_at: 2026-03-17 11:15:03.509465
updated_at: 2026-03-17 11:23:22.214510
description:
As a musician, I want the hardware to be low cost so I can deploy multiple nodes without breaking the bank.


id: S-03
title: Extensible Effects Framework
priority: high
status: idea
node_type: sub_requirement
parent_id: FUNC.SHOW
test_status: not_written
created_at: 2026-03-17 11:15:05.545436
updated_at: 2026-03-17 11:23:18.134752
description:
As a musician, I want the framework of lighting effects to be extensible so I can create new effects and extend existing ones without modifying the core system.


id: S-04
title: MIDI Parameter-Driven Effects
priority: high
status: idea
node_type: sub_requirement
parent_id: FUNC.SHOW
test_status: not_written
created_at: 2026-03-17 11:15:07.576126
updated_at: 2026-03-17 11:23:20.168349
description:
As a musician, I want MIDI note parameters (velocity, channel, note number, etc.) to drive effect parameters so that my playing dynamics directly shape the light show.


id: S-05
title: Hardware Node Logging
priority: medium
status: idea
node_type: sub_requirement
parent_id: NFUNC.OBS
test_status: not_written
created_at: 2026-03-17 11:15:09.610601
updated_at: 2026-03-17 11:23:26.268169
description:
As a developer/operator, I want logging visibility into each hardware node so I can diagnose issues, monitor health, and understand what each node is doing in real time.


id: S-06
title: Control UI
priority: medium
status: idea
node_type: sub_requirement
parent_id: FUNC.UI
test_status: not_written
created_at: 2026-03-17 11:15:11.630416
updated_at: 2026-03-17 11:23:24.235282
description:
As a musician/operator, I want a UI to control configurations, monitor the system, and push OTA firmware updates to hardware nodes.


id: S-07
title: CI/CD Pipeline
priority: high
status: idea
node_type: sub_requirement
parent_id: NFUNC.ENG
test_status: not_written
created_at: 2026-03-17 11:19:24.832633
updated_at: 2026-03-17 11:23:32.365399
description:
As a developer, I want a full CI/CD pipeline to automate building and testing each layer of the application so that every change is validated before deployment.


id: S-08
title: Code-to-Requirement Traceability
priority: high
status: idea
node_type: sub_requirement
parent_id: NFUNC.ENG
test_status: not_written
created_at: 2026-03-17 11:19:26.848252
updated_at: 2026-03-17 11:23:34.401751
description:
As a developer, I need to tie every line of code back to satisfying a requirement so that nothing is built without purpose and nothing required is left unbuilt.


id: S-09
title: Telemetry Reporting
priority: medium
status: idea
node_type: sub_requirement
parent_id: NFUNC.OBS
test_status: not_written
created_at: 2026-03-17 11:19:28.895611
updated_at: 2026-03-17 11:23:28.301503
description:
As an operator, I want telemetry data reported from hardware nodes (CPU, memory, temperature, network stats) so I can understand system health over time.


id: S-10
title: Health Monitoring in UI
priority: medium
status: idea
node_type: sub_requirement
parent_id: NFUNC.OBS
test_status: not_written
created_at: 2026-03-17 11:19:30.929261
updated_at: 2026-03-17 11:23:30.331603
description:
As an operator, I want to view the health status of all hardware nodes in the UI — online/offline, resource usage, error rates — so I can spot problems before they affect the show.


id: FUNC.SHOW
title: Live Show Experience
priority: critical
status: draft
node_type: requirement
parent_id: FUNC
test_status: not_written
created_at: 2026-03-17 11:23:05.901750
updated_at: 2026-03-17 11:29:07.848497
description:
As a musician, I want a programmable light show that reacts to my MIDI performance in real time. Features that define the real-time MIDI-reactive light show experience.


id: S-11
title: MIDI Pass-through to DAW
priority: critical
status: idea
node_type: sub_requirement
parent_id: FUNC.COMMS.MIDI
test_status: not_written
created_at: 2026-03-17 11:33:18.036766
updated_at: 2026-03-17 13:04:16.802823
description:
As a sound engineer, I need MIDI notes arriving at the host's USB input to be forwarded to the USB output connected to my DAW with no more than 2ms latency. No notes are dropped, reordered, or altered.

acceptance_criteria:
- MIDI messages received on the USB input port appear on the USB output port
- Latency between a note arriving at input and departing the output is no more than 2ms
- No messages are dropped under sustained load at maximum MIDI data rate
- Message bytes are identical between input and output (no alteration)
- System continues forwarding while simultaneously processing messages for LED effects


id: FUNC.COMMS
title: Communications
priority: critical
status: draft
node_type: requirement
parent_id: FUNC
test_status: not_written
created_at: 2026-03-17 11:34:38.341421
updated_at: 2026-03-17 11:34:38.341421
description:
All aspects of the communication layers between each node — MIDI signal routing, inter-node messaging, network transport, and latency constraints.


id: FUNC.COMMS.MIDI
title: MIDI Origin to Host Output
priority: critical
status: draft
node_type: sub_requirement
parent_id: FUNC.COMMS
test_status: not_written
created_at: 2026-03-17 11:37:34.075972
updated_at: 2026-03-17 11:55:15.600396
description:
The MIDI signal path from the origin instrument through the host system to the DAW output — pass-through, routing, latency constraints, and message integrity.


id: FUNC.COMMS.H2C
title: Host to Client
priority: high
status: draft
node_type: sub_requirement
parent_id: FUNC.COMMS
test_status: not_written
created_at: 2026-03-17 11:37:36.109195
updated_at: 2026-03-17 11:37:36.109195
description:
Communication from the host (coordinator/UI) to client hardware nodes — configuration pushes, firmware updates, effect assignments, and command delivery.


id: FUNC.COMMS.C2H
title: Client to Host
priority: high
status: draft
node_type: sub_requirement
parent_id: FUNC.COMMS
test_status: not_written
created_at: 2026-03-17 11:38:04.989920
updated_at: 2026-03-17 11:38:04.989920
description:
Communication from client hardware nodes back to the host — log streaming, telemetry reporting, health status, and acknowledgements.


id: S-11.1
title: USB MIDI Input Read
priority: critical
status: idea
node_type: sub_requirement
parent_id: S-11
test_status: not_written
created_at: 2026-03-17 12:00:47.318029
updated_at: 2026-03-17 12:52:31.128373
description:
The host reads MIDI messages from the designated USB input device as they arrive, without blocking or buffering beyond what the USB stack requires.

acceptance_criteria:
- Host can open, use, and recover from disconnection of a USB MIDI input device
- All incoming MIDI messages are read without loss or blocking


id: S-11.2
title: USB MIDI Output Write
priority: critical
status: idea
node_type: sub_requirement
parent_id: S-11
test_status: not_written
created_at: 2026-03-17 12:00:49.355676
updated_at: 2026-03-17 12:56:25.381431
description:
The host writes MIDI messages to the designated USB output device immediately after receiving them from the input.

acceptance_criteria:
- Host can open, use, and recover from disconnection of a USB MIDI output device
- Every message read from input is written to output without blocking the read loop


id: S-11.3
title: Forward Latency Budget
priority: critical
status: idea
node_type: sub_requirement
parent_id: S-11
code_language: python
test_status: not_written
created_at: 2026-03-17 12:00:51.386607
updated_at: 2026-03-17 12:17:44.700903
description:
The time between a MIDI message arriving at the USB input and departing the USB output must not exceed 2ms.

acceptance_criteria:
- End-to-end latency (input read to output write) is measured per message
- 99th percentile latency is at or below 2ms
- Latency is measurable via internal timestamps at input read and output write points

test_spec:
GIVEN the host is running with USB MIDI input and output devices connected, and the forward path is active
WHEN a stream of MIDI note-on messages is sent to the input at maximum MIDI data rate for 10 seconds
THEN the 99th percentile of (output write timestamp - input read timestamp) across all forwarded messages is at or below 2ms


id: S-11.4
title: Message Integrity
priority: critical
status: idea
node_type: sub_requirement
parent_id: S-11
code_language: python
test_status: not_written
created_at: 2026-03-17 12:00:53.436769
updated_at: 2026-03-17 13:04:12.705380
description:
MIDI messages are forwarded with identical bytes in the same order they were received. No messages are dropped, duplicated, or reordered.

acceptance_criteria:
- Output bytes are identical to input bytes for every message
- Message ordering is preserved (FIFO)
- No messages are dropped under sustained maximum MIDI data rate
- No messages are duplicated

test_spec:
GIVEN the host is running with USB MIDI input and output devices open
WHEN a known sequence of 1000 MIDI messages (varied types: note on, note off, CC) is sent to the input
THEN every message appears on the output with identical bytes, in the same order, with no duplicates and no drops


id: S-11.5
title: Non-blocking Forward Path
priority: critical
status: idea
node_type: sub_requirement
parent_id: S-11
code_language: python
test_status: not_written
created_at: 2026-03-17 12:00:55.470801
updated_at: 2026-03-17 13:04:14.754290
description:
The MIDI forwarding path operates independently of LED effect processing. LED computation does not delay or interfere with message forwarding.

acceptance_criteria:
- Forwarding continues at full rate while LED effects are actively computing
- LED processing runs on a separate thread/task from the forward path
- A stalled or slow effect does not cause message drops or latency spikes
- Forward path latency is unaffected regardless of effect complexity

test_spec:
GIVEN the host is running with the MIDI forward path active and an LED effect that takes 50ms per frame
WHEN MIDI messages are sent at maximum data rate for 10 seconds
THEN forward path latency remains at or below 2ms (99th percentile) and no messages are dropped, regardless of effect load


id: PLAN
title: Planning & Execution Standards
priority: medium
status: idea
node_type: pillar
test_status: not_written
created_at: 2026-03-17 12:09:26.824125
updated_at: 2026-03-17 12:11:31.727414
description:
Captures the methodology for how requirements are discovered, organized, decomposed, and verified.

## Process Flow

1. **Collect Stories** — Write user stories as "idea" requirements (As a <role>, I want/need <thing>)
2. **Group into Themes** — Create pillar/epic groupings (Functional, Non-Functional, then sub-themes like Comms, Observability)
3. **Organize** — Re-parent stories under their theme. Merge redundant stories into group descriptions
4. **Refine Descriptions & AC** — Each story gets acceptance criteria that define what "done" means
5. **Decompose** — Break stories into child requirements that each satisfy one or more AC lines from the parent
6. **Repeat** — Drill children until each leaf is independently testable and measurable
7. **Write Test Specs** — GIVEN/WHEN/THEN at the leaf level. If all leaves pass, the parent AC is satisfied by definition
8. **Audit Quality Gates** — Run each requirement through TMCS validation:
   - **Traceable**: Does it have a parent and description? If not, link it or write one
   - **Measurable**: Is the AC quantifiable? Can you write a pass/fail test? If vague, rewrite the AC
   - **Consistent**: Does it contradict any sibling requirements? If so, reconcile or split
   - **Single-purpose**: Does it serve exactly one concern? If the title or AC contains "and", split into separate requirements
   - Fix violations before proceeding. Splitting a requirement creates new children that must themselves pass TMCS
   - Re-audit after any structural change (split, merge, re-parent)
9. **Implement & Test** — Write test code and implementation code against the leaf specs

## Traceability Rules

- Every line of code traces back to a leaf requirement
- Every leaf has a test spec with GIVEN/WHEN/THEN
- Every leaf's AC rolls up to satisfy a parent's AC
- Parent AC is proven by its children passing — no separate parent-level test needed
- Cross-cutting concerns use "also satisfies" links to connect to multiple parents

## Requirement Quality Gates (TMCS)

- **T**raceable — auto-calculated: has parent and description
- **M**easurable — user asserts: AC is quantifiable and testable
- **C**onsistent — user asserts: no contradictions with siblings
- **S**ingle-purpose — user asserts: serves exactly one concern

## Decisions

- Tech stack decisions (language, framework) are captured on the requirement before writing test/impl code
- Decisions flow down — a parent's language choice applies to children unless overridden


id: S-05.1
title: Latency Violation Alerting
priority: medium
status: idea
node_type: sub_requirement
parent_id: S-05
code_language: python
test_status: not_written
created_at: 2026-03-17 12:15:46.459707
updated_at: 2026-03-17 12:15:46.459707
description:
When MIDI forward latency exceeds the 2ms budget, the system logs a warning with the measured latency value and message details.

acceptance_criteria:
- A warning is logged when any single message exceeds 2ms forward latency
- The log entry includes the measured latency value and MIDI message type
- Logging does not add latency to the forward path


id: S-11.1.1
title: USB MIDI Input Device Lifecycle
priority: critical
status: idea
node_type: leaf
parent_id: S-11.1
code_language: python
test_status: not_written
created_at: 2026-03-17 12:26:15.750153
updated_at: 2026-03-17 12:44:50.512092
description:
The host opens the designated USB MIDI input device on startup and handles connection state changes gracefully.

acceptance_criteria:
- Host opens the designated USB MIDI input device on startup
- System detects if the input device is disconnected
- System does not crash on disconnect

test_spec:
GIVEN the host application is starting with a USB MIDI input device connected
WHEN the application initializes
THEN the designated USB MIDI input device is opened successfully

GIVEN the host is running with an active USB MIDI input device
WHEN the device is physically disconnected
THEN the system detects the disconnection and continues running without crash


id: S-11.1.2
title: MIDI Message Read Loop
priority: critical
status: idea
node_type: leaf
parent_id: S-11.1
code_language: python
test_status: not_written
created_at: 2026-03-17 12:26:17.767990
updated_at: 2026-03-17 12:44:52.558059
description:
An async read loop continuously reads all incoming MIDI messages from the input device without loss and without blocking other system operations.

acceptance_criteria:
- All incoming MIDI messages are read from the device
- Read loop runs asynchronously and does not block other operations
- No messages are lost under sustained maximum MIDI data rate

test_spec:
GIVEN the host is running with the USB MIDI input device open
WHEN MIDI note-on messages are sent at maximum MIDI data rate for 10 seconds
THEN all messages are read from the device with zero loss and the read loop does not block other operations


id: S-05.2
title: Device Disconnection Alerting
priority: medium
status: idea
node_type: sub_requirement
parent_id: S-05
code_language: python
test_status: not_written
created_at: 2026-03-17 12:41:00.591318
updated_at: 2026-03-17 12:41:00.591318
description:
When a USB MIDI input device is disconnected, the system reports the event to the logging subsystem with device identity and timestamp.

acceptance_criteria:
- A log entry is created when the input device disconnects
- The log entry includes device name/ID and timestamp
- Logging does not delay or interfere with disconnect handling


id: S-11.2.1
title: USB MIDI Output Device Lifecycle
priority: critical
status: idea
node_type: leaf
parent_id: S-11.2
code_language: python
test_status: not_written
created_at: 2026-03-17 12:54:23.916673
updated_at: 2026-03-17 12:56:27.417081
description:
The host opens the designated USB MIDI output device on startup and handles connection state changes gracefully.

acceptance_criteria:
- Host opens the designated USB MIDI output device on startup
- System detects if the output device is disconnected
- System does not crash on disconnect

test_spec:
GIVEN the host application is starting with a USB MIDI output device connected
WHEN the application initializes
THEN the designated USB MIDI output device is opened successfully

GIVEN the host is running with an active USB MIDI output device
WHEN the device is physically disconnected
THEN the system detects the disconnection and continues running without crash


id: S-11.2.2
title: MIDI Message Write Loop
priority: critical
status: idea
node_type: leaf
parent_id: S-11.2
code_language: python
test_status: not_written
created_at: 2026-03-17 12:54:25.965809
updated_at: 2026-03-17 12:56:29.449743
description:
Every MIDI message read from the input device is written to the output device without blocking the input read loop.

acceptance_criteria:
- Every message read from the input is written to the output device
- Write operations do not block the input read loop
- No messages are skipped or lost during writing

test_spec:
GIVEN the host is running with USB MIDI input and output devices open
WHEN MIDI note-on messages are sent to the input at maximum MIDI data rate for 10 seconds
THEN every message read from input appears on the output with zero loss and the input read loop is not blocked


id: S-05.3
title: Output Device Disconnection Alerting
priority: medium
status: idea
node_type: sub_requirement
parent_id: S-05
code_language: python
test_status: not_written
created_at: 2026-03-17 12:54:27.982282
updated_at: 2026-03-17 12:54:27.982282
description:
When a USB MIDI output device is disconnected, the system reports the event to the logging subsystem with device identity and timestamp.

acceptance_criteria:
- A log entry is created when the output device disconnects
- The log entry includes device name/ID and timestamp
- Logging does not delay or interfere with disconnect handling


