openbitdo/spec/requirements.yaml

metadata:
  version: 1
  owner: cleanroom-sdk
  status: draft
requirements:
  - id: REQ-PROT-001
    title: CommandFrame model
    description: SDK shall expose CommandFrame with command id, payload, report id, and expected response metadata.
    acceptance: Unit tests validate frame creation for all CommandId values.
  - id: REQ-PROT-002
    title: Response validation
    description: SDK shall validate responses using command-specific byte signatures.
    acceptance: Parser rejection tests fail malformed responses and accept matching responses.
  - id: REQ-PROT-003
    title: Deterministic retries
    description: SDK shall retry reads on timeout/malformed responses using configured retry count.
    acceptance: Retry tests cover delayed and partial responses.
  - id: REQ-PROT-004
    title: Report width support
    description: SDK shall support both 64-byte reports and variable-length boot/firmware frames.
    acceptance: Encode/decode tests cover Report64 and variable report wrappers.

  - id: REQ-PID-001
    title: PID registry completeness
    description: SDK shall include all PIDs present in sanitized pid_matrix.csv.
    acceptance: pid registry coverage test count equals pid_matrix.csv row count.
  - id: REQ-PID-002
    title: Support-level gating
    description: detect-only devices shall reject unsupported operations with UnsupportedForPid.
    acceptance: Capability gating tests verify rejection for unsafe operations on detect-only PIDs.

  - id: REQ-SAFE-001
    title: Unsafe command dual confirmation
    description: Unsafe commands shall require both unsafe and brick-risk acknowledgement flags.
    acceptance: Boot safety tests verify command denial without both flags.
  - id: REQ-SAFE-002
    title: Experimental command policy
    description: Inferred commands shall require experimental mode.
    acceptance: Inferred-command tests verify denial without experimental flag.

  - id: REQ-TEST-001
    title: Golden profile fixture
    description: SDK shall parse and serialize profile blobs compatible with golden binary fixture.
    acceptance: Profile serialization test round-trips fixture payload.
  - id: REQ-TEST-002
    title: Beginner-first report output
    description: User-facing reports shall be TOML-only and hidden on happy path.
    acceptance: Report tests assert TOML persistence for diagnostics/failure flows and no JSON output path.
  - id: REQ-TEST-003
    title: Clean-room guard
    description: CI shall fail if cleanroom/sdk references forbidden dirty-room locations or tokens.
    acceptance: cleanroom guard script is executed in CI and by integration test.
  - id: REQ-JP108-001
    title: JP108 dedicated mapping read/write
    description: SDK shall support reading and writing JP108 dedicated button mappings for A/B/K1-K8.
    acceptance: Unit and hardware tests verify read/write/readback for A, B, and at least one K button.
  - id: REQ-JP108-002
    title: JP108 firmware path
    description: SDK shall support JP108 firmware preflight and transfer with existing unsafe gates.
    acceptance: Hardware smoke validates JP108 firmware preflight and guarded transfer path.
  - id: REQ-U2-001
    title: Ultimate2 core profile support
    description: SDK shall support Ultimate2 mode, slot, and core button-map operations.
    acceptance: Unit and hardware tests verify mode read/set/readback and slot/profile read/write/readback.
  - id: REQ-U2-002
    title: Ultimate2 firmware path
    description: SDK shall support Ultimate2 firmware preflight and transfer with existing unsafe gates.
    acceptance: Hardware smoke validates Ultimate2 firmware preflight and guarded transfer path.
  - id: REQ-WIZ-001
    title: Beginner guided configuration flows
    description: TUI wizard shall provide dedicated JP108 and Ultimate2 configuration paths with mouse support.
    acceptance: TUI tests verify end-to-end wizard transitions for mapping/profile apply and guided button test.
  - id: REQ-WIZ-002
    title: Backup and rollback safety
    description: Mapping/profile writes shall create rollback snapshots and auto-rollback on failure.
    acceptance: App-core tests verify backup creation, rollback on failure, and deterministic retry guidance.
  - id: REQ-HW-001
    title: Required hardware gates for target lines
    description: CI shall enforce required blocking hardware jobs for Ultimate2 and JP108 targets.
    acceptance: workflow includes required jobs that fail deterministically on missing fixture or command failure.
  - id: REQ-DR-001
    title: Dossier completeness
    description: Every wave target PID shall have sanitized dossier files for each scoped operation group.
    acceptance: `spec/dossiers/<pid_hex>/*.toml` exists and includes all required schema fields.
  - id: REQ-DR-002
    title: Dossier traceability
    description: Dossiers and command matrix rows shall be linked by stable dossier IDs.
    acceptance: command matrix `dossier_id` references an existing dossier artifact.
  - id: REQ-DR-W2-001
    title: Wave 2 dossier minimum per PID
    description: Each Wave 2 target PID shall include `core_diag`, `mode_or_profile_read`, and `firmware_preflight` dossiers.
    acceptance: lint check confirms all three required dossier files exist for every Wave 2 PID.
  - id: REQ-DR-W2-002
    title: Wave 2 dossier state model and placeholders
    description: Every Wave 2 dossier shall include state machine, runtime placeholder, and hardware placeholder sections.
    acceptance: dossier lint rejects files missing `state_machine`, `runtime_placeholder`, or `hardware_placeholder`.
  - id: REQ-PROM-001
    title: Strict promotion gate
    description: Promotion to full support requires static evidence plus runtime traces and hardware read/write/readback.
    acceptance: no PID is promoted without all three evidence signals marked complete.
  - id: REQ-PROM-002
    title: Candidate read-only enforcement
    description: candidate-readonly devices shall permit detect/diag reads but reject safe writes and unsafe operations.
    acceptance: command gating tests reject write/firmware commands for candidate-readonly PIDs.
  - id: REQ-PROM-W2-001
    title: Wave 2 promotion block
    description: Wave 2 target devices shall remain candidate-readonly until runtime and hardware placeholders are satisfied.
    acceptance: Wave 2 command matrix rows set `promotion_gate=blocked/no_runtime` and evidence runtime/hardware set to `no`.
  - id: REQ-PROM-W2-002
    title: Firmware preflight only for Wave 2
    description: Wave 2 firmware coverage shall remain metadata/preflight only with no transfer/write enablement.
    acceptance: firmware transfer commands remain blocked for Wave 2 candidate-readonly PIDs.
  - id: REQ-COMM-001
    title: Structured community intake
    description: Community evidence submissions shall follow a structured sanitized template.
    acceptance: issue templates collect VID/PID, operation group, sanitized request/response structure, and repro notes.
  - id: REQ-COMM-002
    title: Clean-room intake boundary
    description: Community submissions must forbid raw vendor/decompiled snippet carryover.
    acceptance: template and docs explicitly prohibit raw snippet submission.
  - id: REQ-GH-001
    title: Release-governance variables
    description: Repository variables for AUR/Homebrew publication gates shall be configured through GitHub settings.
    acceptance: variables `AUR_PUBLISH_ENABLED`, `HOMEBREW_PUBLISH_ENABLED`, and `HOMEBREW_TAP_REPO` are present.
  - id: REQ-GH-002
    title: Hardware-constrained required checks
    description: Branch protection required checks shall reflect currently available hardware fixtures.
    acceptance: required checks include `hardware-108jp` and `hardware-ultimate2`, excluding unavailable hardware families.