EdisonJwa
02ffadfa52
Applies the gen2 desktop-PTT review summary
(`gen2/chanora-desktop-ptt-review-summary-v0.9.2.md`) to our doc set
with the owner rulings PTT-OPEN-001 through PTT-OPEN-006 resolved as
accepted decisions DEC-023 through DEC-028:
* DEC-023 Windows Global PTT P0 / MVP
* DEC-024 macOS Global PTT P0 / MVP with permission UX
* DEC-025 Linux officially-tested env: GNOME on Wayland only
* DEC-026 Mouse side buttons supported (Win + macOS; Linux portal)
* DEC-027 PTT diagnostics: capability + availability only, no
raw key codes ever
* DEC-028 Missed-key-up watchdog: P0
Requirements (SysRS / SRS) and architecture (SysDes / SAD / SDD)
gain the desktop-PTT ID set the gen2 summary describes:
SysRS-296..302 -> SysDes-142..148
-> SRS-195..203
-> SAD-071..079
-> SDD-081..092
ID totals advance from 295 / 141 / 194 / 70 / 80 to 302 / 148 / 203
/ 79 / 92. The strict layered sourcing rule (`SRS -> SysDes` only,
`SAD -> SRS` only, `SDD -> SAD` only) is preserved; the
`tools/validate_docs.py` validator reports zero undefined refs and
zero direct-layer-rule violations.
New document:
* `docs/architecture/desktop-ptt-architecture.md` — capability
ladder (L0Focused, L1GlobalShortcut, L2GlobalHoldToTalk,
L3GlobalWithMouseButtons, L4DeviceAware reserved), Windows /
macOS / Linux strategies, privacy rule, audio-gate rule,
missed-key-up watchdog, release-readiness evidence requirement,
traceability summary.
Doc addenda (Baseline Candidate 0.9.3):
* `privacy/privacy-policy.md` — no raw key history, capability-
dependent Global PTT, UI reflects actual runtime capability
* `security/threat-model.md` — THREAT-PTT-001..006
* `security/diagnostic-redaction-audit-report.md` —
REDACT-PTT-001..006 banned field list enforced by `PttSanitizer`
* `release/platform-release-policy.md` — per-platform evidence
fields, no over-claim on untested Linux compositors
* `release/release-readiness-go-nogo-record.md` — RR-PTT-001..008
release-readiness items
* `verification/swe4-unit-verification-plan.md` —
SWE4-UV-035..039
* `verification/swe5-software-integration-verification-plan.md` —
SWE5-IV-015
* `verification/swe6-software-verification-plan.md` — SWE6-SV-017
* `verification/sys4-system-integration-verification-plan.md` —
SYS4-SIV-016
* `governance/traceability-matrix.md` — full PTT trace rows +
verification map
* `governance/decision-impact-assessment.md` — DEC-023..028
impact matrix
* `governance/product-decision-register.md` v0.9.9 entry
recording DEC-023..028 in the decision table and the status
table at §7
* `governance/document-index.md` — adds
`desktop-ptt-architecture.md` to the controlled set
* `architecture/proof-of-concept-plan.md` —
PoC-PTT-001..005 platform items
* `references/external-references.md` — Windows Raw Input,
macOS event-tap, Linux GlobalShortcuts portal references
* Both validation reports
(`baseline-candidate-validation-report.md`,
`repo-format-validation-report.md`) bumped to v0.9.3 with the
new ID totals (302 / 148 / 203 / 79 / 92).
README §"Desktop Push-to-Talk" added between Architecture Overview
and Repository Layout: capability levels, per-platform strategy,
privacy posture, missed-key-up watchdog.
Tooling:
* `tools/validate_docs.py` copied from the gen2 zip into the
repo tree (was previously available only inside the zip).
Reports zero undefined refs, zero direct-layer-rule violations,
English-only CJK check passes. The 35 "old package-style
filename" hits are pre-existing and identical to the gen2
baseline (they live in `path-migration-map.md` and config-ID
headers of governance docs and are intentional per the path
migration policy).
* `.gitignore` adds `/gen2/` so the externally-provided review
package does not enter the repo.
No code changes in this commit; B (the implementation split into
`transmit_active` / `capture_active`, `PttCapabilityLevel`
reporting, `PttSanitizer` diagnostics rule, and the UI capability
badge) follows in a separate commit.
419 lines
16 KiB
Markdown
419 lines
16 KiB
Markdown
|
|
# Chanora SWE.4 Software Unit Verification Plan
|
|
|
|
**Document type:** Software Unit Verification Plan
|
|
**Process alignment:** ASPICE SWE.4 Software Unit Verification
|
|
**Version:** 0.9.2
|
|
**Status:** Baseline Candidate
|
|
**Language:** English
|
|
**Product:** Chanora
|
|
**Verification object:** Software units defined by SDD
|
|
**Direct source layer:** SDD only
|
|
|
|
**Repo path:** `docs/verification/swe4-unit-verification-plan.md` ---
|
|
|
|
## 1. Purpose
|
|
|
|
This document defines the software unit verification strategy for Chanora. It verifies that software units implement the Software Detailed Design.
|
|
|
|
This document is downstream of SDD and shall not bypass the document hierarchy.
|
|
|
|
```text
|
|
SysRS -> SysDes -> SRS -> SAD -> SDD -> SWE.4 Unit Verification
|
|
```
|
|
|
|
Direct source rule:
|
|
|
|
```text
|
|
SWE.4 unit verification items shall link directly to SDD only.
|
|
```
|
|
|
|
## 2. Verification Scope
|
|
|
|
In scope:
|
|
|
|
- Flutter unit tests
|
|
- Flutter widget-level unit verification where a widget is treated as a software unit
|
|
- Dart static analysis
|
|
- Dart code review
|
|
- Rust unit tests
|
|
- Rust static analysis
|
|
- Rust code review
|
|
- Unit-level regression verification
|
|
- Unit-level interface boundary tests
|
|
- Unit-level localization, Unicode, design-token, and diagnostics verification
|
|
|
|
Out of scope:
|
|
|
|
- Software integration verification across components; handled by SWE.5.
|
|
- Fully integrated software verification against SRS; handled by SWE.6.
|
|
- System integration verification against SysDes; handled by SYS.4.
|
|
|
|
## 3. Unit Verification Strategy
|
|
|
|
| Verification type | Applies to | Purpose |
|
|
|---|---|---|
|
|
| Static analysis | Dart, Rust | Detect structural, lint, safety, style, and maintainability issues |
|
|
| Code review | Dart, Rust, build scripts | Confirm design compliance and maintainability |
|
|
| Unit tests | Dart, Rust | Verify individual units against SDD behavior |
|
|
| Widget tests | Flutter widgets | Verify component rendering, semantics, and state behavior |
|
|
| Golden tests | Design-system components | Verify stable UI rendering where appropriate |
|
|
| Localization tests | Localization service and accessibility labels | Verify fallback, keys, and localized display strings |
|
|
| Unicode tests | Protocol/bridge/text-boundary units | Verify UTF-8 and multilingual content handling |
|
|
| Regression tests | Changed units | Confirm unchanged behavior remains valid after modifications |
|
|
|
|
## 4. Entry Criteria
|
|
|
|
| Criterion | Description |
|
|
|---|---|
|
|
| SDD baseline available | Unit design items and source SAD links are available. |
|
|
| Unit implementation available | The unit exists in source code or executable test double form. |
|
|
| Unit test environment available | Flutter and/or Rust test infrastructure is configured. |
|
|
| Verification measure defined | Test, review, or static analysis objective is defined. |
|
|
| Pass/fail criteria defined | Expected result is objective and reviewable. |
|
|
|
|
## 5. Exit Criteria
|
|
|
|
| Criterion | Description |
|
|
|---|---|
|
|
| Selected unit verification measures executed | Tests, reviews, and analyses required for the release scope are complete. |
|
|
| Results recorded | Verification results are stored in test reports or review records. |
|
|
| Nonconformances recorded | Failures are recorded for problem resolution. |
|
|
| Traceability complete | Each unit verification item traces to SDD and result evidence. |
|
|
| Regression scope complete | Changed units have selected regression measures executed. |
|
|
|
|
## 6. Unit Verification Measures
|
|
|
|
**SWE4-UV-001**: Verify `ChanoraApp` initialization order.
|
|
|
|
- Source SDD: SDD-001, SDD-045
|
|
- Verification method: Flutter unit/integration test
|
|
- Pass criteria: Theme, localization, platform services, routing, and adaptive shell initialize before feature rendering.
|
|
- Evidence: Test result
|
|
|
|
**SWE4-UV-002**: Verify `ChanoraThemeFactory` Material 3 theme creation.
|
|
|
|
- Source SDD: SDD-002, SDD-003
|
|
- Verification method: Dart unit test
|
|
- Pass criteria: Light and dark Material 3 ThemeData objects are created with valid ColorScheme and TextTheme values.
|
|
- Evidence: Test result
|
|
|
|
**SWE4-UV-003**: Verify `ChanoraSemanticColors` connection token behavior.
|
|
|
|
- Source SDD: SDD-004, SDD-006
|
|
- Verification method: Dart unit test
|
|
- Pass criteria: All connection semantic roles are present and do not require feature-screen hardcoding.
|
|
- Evidence: Test result
|
|
|
|
**SWE4-UV-004**: Verify voice semantic token behavior.
|
|
|
|
- Source SDD: SDD-005, SDD-006
|
|
- Verification method: Dart unit test
|
|
- Pass criteria: Speaking, muted, deafened, and push-to-talk active states are available through semantic tokens.
|
|
- Evidence: Test result
|
|
|
|
**SWE4-UV-005**: Verify feature widgets use theme accessors rather than hardcoded semantic values.
|
|
|
|
- Source SDD: SDD-010
|
|
- Verification method: Static inspection
|
|
- Pass criteria: Feature widgets do not construct product semantic token values directly.
|
|
- Evidence: Review record
|
|
|
|
**SWE4-UV-006**: Verify adaptive shell window classification.
|
|
|
|
- Source SDD: SDD-011, SDD-012
|
|
- Verification method: Dart unit test
|
|
- Pass criteria: Compact, medium, and expanded classes are selected deterministically.
|
|
- Evidence: Test result
|
|
|
|
**SWE4-UV-007**: Verify `CompactShell` layout behavior.
|
|
|
|
- Source SDD: SDD-013
|
|
- Verification method: Flutter widget test
|
|
- Pass criteria: Compact shell renders a single-column layout and mobile navigation entry points.
|
|
- Evidence: Test result
|
|
|
|
**SWE4-UV-008**: Verify `MediumShell` layout behavior.
|
|
|
|
- Source SDD: SDD-014
|
|
- Verification method: Flutter widget test
|
|
- Pass criteria: Medium shell renders side navigation or navigation rail behavior.
|
|
- Evidence: Test result
|
|
|
|
**SWE4-UV-009**: Verify `ExpandedShell` persistent pane behavior.
|
|
|
|
- Source SDD: SDD-015
|
|
- Verification method: Flutter widget test
|
|
- Pass criteria: Expanded shell renders persistent side pane and VoiceBar slot.
|
|
- Evidence: Test result
|
|
|
|
**SWE4-UV-010**: Verify connection status presentation uses non-color-only cues.
|
|
|
|
- Source SDD: SDD-016, SDD-022
|
|
- Verification method: Dart unit test, widget test
|
|
- Pass criteria: The presenter exposes label, icon, semantic label, and severity token.
|
|
- Evidence: Test result
|
|
|
|
**SWE4-UV-011**: Verify `ChanoraVoiceBar` exposed properties.
|
|
|
|
- Source SDD: SDD-017, SDD-018
|
|
- Verification method: Flutter widget test
|
|
- Pass criteria: Mute, deaf, push-to-talk, input meter, current channel, and latency properties render correctly.
|
|
- Evidence: Test result
|
|
|
|
**SWE4-UV-012**: Verify `ChanoraChannelTree` data and interaction behavior.
|
|
|
|
- Source SDD: SDD-019, SDD-020
|
|
- Verification method: Flutter widget test
|
|
- Pass criteria: Channel hierarchy, selected state, expansion state, join intent, and context-menu intent operate as designed.
|
|
- Evidence: Test result
|
|
|
|
**SWE4-UV-013**: Verify `ChanoraClientTile` state semantics.
|
|
|
|
- Source SDD: SDD-021
|
|
- Verification method: Widget test, accessibility test
|
|
- Pass criteria: Client status is available through text/icon/semantic cues and not color alone.
|
|
- Evidence: Test result
|
|
|
|
**SWE4-UV-014**: Verify localized semantic labels for icon-only buttons.
|
|
|
|
- Source SDD: SDD-024, SDD-031, SDD-032
|
|
- Verification method: Accessibility test, localization unit test
|
|
- Pass criteria: Icon-only controls expose localized semantic labels with fallback.
|
|
- Evidence: Test result
|
|
|
|
**SWE4-UV-015**: Verify keyboard focus traversal.
|
|
|
|
- Source SDD: SDD-025
|
|
- Verification method: Widget test
|
|
- Pass criteria: Primary interactive controls can be traversed in a logical order.
|
|
- Evidence: Test result
|
|
|
|
**SWE4-UV-016**: Verify text-scale resilience of critical controls.
|
|
|
|
- Source SDD: SDD-026
|
|
- Verification method: Accessibility widget test
|
|
- Pass criteria: Critical controls remain reachable under increased text scale.
|
|
- Evidence: Test result
|
|
|
|
**SWE4-UV-017**: Verify platform inset service unit behavior.
|
|
|
|
- Source SDD: SDD-027, SDD-030
|
|
- Verification method: Unit test with platform test doubles
|
|
- Pass criteria: Insets are normalized and exposed to the shell.
|
|
- Evidence: Test result
|
|
|
|
**SWE4-UV-018**: Verify back intent service behavior.
|
|
|
|
- Source SDD: SDD-028
|
|
- Verification method: Unit test with platform test doubles
|
|
- Pass criteria: Platform back events map to expected route-level intents.
|
|
- Evidence: Test result
|
|
|
|
**SWE4-UV-019**: Verify localization fallback.
|
|
|
|
- Source SDD: SDD-031, SDD-032, SDD-033
|
|
- Verification method: Unit test
|
|
- Pass criteria: Missing localized strings fall back deterministically.
|
|
- Evidence: Test result
|
|
|
|
**SWE4-UV-020**: Verify server-content pass-through.
|
|
|
|
- Source SDD: SDD-034
|
|
- Verification method: Unit test
|
|
- Pass criteria: Server-provided content is not translated by product localization.
|
|
- Evidence: Test result
|
|
|
|
**SWE4-UV-021**: Verify Unicode text boundary behavior.
|
|
|
|
- Source SDD: SDD-035, SDD-036, SDD-037
|
|
- Verification method: Unit test
|
|
- Pass criteria: Valid multilingual Unicode content is preserved; invalid external encodings are handled at boundaries.
|
|
- Evidence: Test result
|
|
|
|
**SWE4-UV-022**: Verify diagnostic Unicode preservation and redaction behavior.
|
|
|
|
- Source SDD: SDD-038, SDD-041, SDD-050, SDD-054
|
|
- Verification method: Unit test, security review
|
|
- Pass criteria: Secrets are redacted while multilingual content is preserved.
|
|
- Evidence: Test result, review record
|
|
|
|
**SWE4-UV-023**: Verify locale-aware formatting.
|
|
|
|
- Source SDD: SDD-040
|
|
- Verification method: Unit test
|
|
- Pass criteria: Dates, times, numbers, and timestamps format through localization utilities.
|
|
- Evidence: Test result
|
|
|
|
**SWE4-UV-024**: Verify traceability checker behavior.
|
|
|
|
- Source SDD: SDD-043, SDD-044, SDD-055, SDD-056, SDD-066, SDD-067
|
|
- Verification method: Unit test / script test
|
|
- Pass criteria: Invalid direct-layer references are detected.
|
|
- Evidence: Test result
|
|
|
|
**SWE4-UV-025**: Verify bridge DTO safety.
|
|
|
|
- Source SDD: SDD-046
|
|
- Verification method: Unit test, static inspection
|
|
- Pass criteria: Bridge DTOs do not expose internal Rust implementation types.
|
|
- Evidence: Test result, review record
|
|
|
|
**SWE4-UV-026**: Verify Rust core event mapping.
|
|
|
|
- Source SDD: SDD-047
|
|
- Verification method: Rust unit test
|
|
- Pass criteria: Core events map deterministically to view model deltas.
|
|
- Evidence: Test result
|
|
|
|
**SWE4-UV-027**: Verify voice view model separation from DSP.
|
|
|
|
- Source SDD: SDD-048
|
|
- Verification method: Code review, unit test
|
|
- Pass criteria: Voice UI receives status values and does not perform audio DSP.
|
|
- Evidence: Review record, test result
|
|
|
|
**SWE4-UV-028**: Verify storage facade isolation.
|
|
|
|
- Source SDD: SDD-049
|
|
- Verification method: Static inspection, unit test
|
|
- Pass criteria: Feature widgets do not directly call database APIs.
|
|
- Evidence: Review record, test result
|
|
|
|
**SWE4-UV-029**: Verify interface detail catalog completeness.
|
|
|
|
- Source SDD: SDD-059, SDD-060
|
|
- Verification method: Review
|
|
- Pass criteria: Unit-level interface entries include required details where applicable.
|
|
- Evidence: Review record
|
|
|
|
**SWE4-UV-030**: Verify unit construction and review records.
|
|
|
|
- Source SDD: SDD-064, SDD-065, SDD-068, SDD-069, SDD-070
|
|
- Verification method: Review
|
|
- Pass criteria: Unit construction, review, verification handoff, and registry records exist for release scope units.
|
|
- Evidence: Review record
|
|
|
|
## 7. Traceability Matrix
|
|
|
|
| SDD Range | SWE.4 Coverage |
|
|
|---|---|
|
|
| SDD-001 through SDD-010 | SWE4-UV-001 through SWE4-UV-005 |
|
|
| SDD-011 through SDD-018 | SWE4-UV-006 through SWE4-UV-011 |
|
|
| SDD-019 through SDD-026 | SWE4-UV-012 through SWE4-UV-016 |
|
|
| SDD-027 through SDD-037 | SWE4-UV-017 through SWE4-UV-021 |
|
|
| SDD-038 through SDD-050 | SWE4-UV-022 through SWE4-UV-028 |
|
|
| SDD-051 through SDD-070 | SWE4-UV-029 through SWE4-UV-030 |
|
|
|
|
## 8. Result Reporting
|
|
|
|
Unit verification results shall be summarized in a unit verification summary report including:
|
|
|
|
- verification scope
|
|
- selected verification measures
|
|
- skipped measures and rationale
|
|
- pass/fail result
|
|
- nonconformances
|
|
- regression scope
|
|
- residual risks
|
|
- release recommendation
|
|
|
|
## 9. Change History
|
|
|
|
| Version | Date | Description |
|
|
|---|---|---|
|
|
| 0.1.0 | 2026-05-14 | Initial SWE.4 unit verification plan derived from SDD v0.3. |
|
|
|
|
---
|
|
|
|
## 10. Platform Decision Unit Verification Addendum
|
|
|
|
**SWE4-UV-031**: Verify iOS and Android build configuration units.
|
|
|
|
- Source SDD: SDD-071, SDD-072, SDD-073
|
|
- Verification method: Static inspection, platform test
|
|
- Pass criteria: iOS minimum runtime, Apple SDK gate, Android minimum runtime, and Android target SDK configuration are inspectable and match release policy.
|
|
- Evidence: Test result, release inspection
|
|
|
|
**SWE4-UV-032**: Verify single active connection enforcement.
|
|
|
|
- Source SDD: SDD-074
|
|
- Verification method: Unit test
|
|
- Pass criteria: Attempting to create a second active MVP connection is rejected or routed through a controlled disconnect/switch policy.
|
|
- Evidence: Test result
|
|
|
|
**SWE4-UV-033**: Verify audio processing defaults and backend selection.
|
|
|
|
- Source SDD: SDD-075, SDD-076
|
|
- Verification method: Unit test, audio test
|
|
- Pass criteria: AEC, AGC, Noise Suppression, and High-Pass Filter default to enabled where supported and stable; backend selector prefers platform-native processing.
|
|
- Evidence: Test result
|
|
|
|
**SWE4-UV-034**: Verify local database, secret storage, bridge, and diagnostics privacy gate units.
|
|
|
|
- Source SDD: SDD-077, SDD-078, SDD-079, SDD-080
|
|
- Verification method: Unit test, security inspection
|
|
- Pass criteria: Non-secret storage, secret storage, typed bridge DTOs, and disabled automatic upload/crash behavior match detailed design.
|
|
- Evidence: Test result, security review
|
|
|
|
**SWE4-UV-035**: Verify `DesktopPttBackend` trait + `PttCapabilityLevel` enum + `FocusedPttBackend` units.
|
|
|
|
- Source SDD: SDD-081, SDD-082, SDD-087
|
|
- Verification method: Unit test
|
|
- Pass criteria: Trait surface compiles for every implementation; enum `as_str()` mapping is unambiguous; `FocusedPttBackend` reports `L0Focused` and forwards `set_ptt` events into `AudioTransmitGate` unchanged.
|
|
- Evidence: Test result
|
|
|
|
**SWE4-UV-036**: Verify Windows / macOS / Linux platform backend units in isolation.
|
|
|
|
- Source SDD: SDD-083, SDD-084, SDD-085, SDD-086
|
|
- Verification method: Unit test (with mocked OS surfaces), Platform Test (Windows / macOS / GNOME-Wayland reference hosts)
|
|
- Pass criteria: Each backend reports the expected `PttCapabilityLevel` for the current host configuration; the ladder falls through to `FocusedPttBackend` when its preferred OS API is unavailable.
|
|
- Evidence: Test result, platform-test trace
|
|
|
|
**SWE4-UV-037**: Verify `PttController` + `AudioTransmitGate` units.
|
|
|
|
- Source SDD: SDD-088, SDD-089
|
|
- Verification method: Unit test
|
|
- Pass criteria: `PttController::set_binding` rebinds the active backend without dropping `AudioTransmitGate`; `AudioTransmitGate::subscribe()` returns a `watch::Receiver` that delivers every transition the gate observes.
|
|
- Evidence: Test result
|
|
|
|
**SWE4-UV-038**: Verify `PttSanitizer` and `PttCapabilityBadge` units.
|
|
|
|
- Source SDD: SDD-090, SDD-091
|
|
- Verification method: Unit test, UI review
|
|
- Pass criteria: `PttSanitizer` drops records whose field names match the banned list (`key_code`, `scan_code`, `virtual_key`, `vk`, `keysym`, `keysym_string`, `key_sequence`); `PttCapabilityBadge` renders the correct label and explanation sheet for each `PttCapabilityLevel`.
|
|
- Evidence: Test result, UI screenshot
|
|
|
|
**SWE4-UV-039**: Verify `MissedKeyUpWatchdog` unit.
|
|
|
|
- Source SDD: SDD-092
|
|
- Verification method: Unit test (tokio time-paused)
|
|
- Pass criteria: After a simulated `false -> true -> (timeout elapsed)` sequence the watchdog calls `AudioTransmitGate::set(false)` exactly once and emits a sanitised diagnostic record naming only `capability_level` and `backend_id`.
|
|
- Evidence: Test result
|
|
|
|
| SDD Range | SWE.4 Coverage |
|
|
|---|---|
|
|
| SDD-071 through SDD-080 | SWE4-UV-031 through SWE4-UV-034 |
|
|
| SDD-081 through SDD-092 | SWE4-UV-035 through SWE4-UV-039 |
|
|
|
|
|
|
## Baseline Candidate 0.9.1 Update
|
|
|
|
| Version | Date | Description |
|
|
|---|---|---|
|
|
| 0.9.1 | 2026-05-14 | Updated baseline after product decision closure: Apple App Store SDK gate uses Xcode 26+ and iOS 26 / iPadOS 26 SDK+ since 2026-04-28, platform baselines and decision traceability propagated across the document set. |
|
|
|
|
|
|
## Baseline Candidate 0.9.2 Update
|
|
|
|
| Version | Date | Description |
|
|
|---|---|---|
|
|
| 0.9.2 | 2026-05-14 | Corrected Apple App Store Connect upload gate to 2026-04-28 and checked full-package naming, references, and coverage. |
|
|
|
|
|
|
## Baseline Candidate 0.9.3 Update
|
|
|
|
| Version | Date | Description |
|
|
|---|---|---|
|
|
| 0.9.3 | 2026-05-15 | Added desktop PTT unit-verification items SWE4-UV-035 through SWE4-UV-039: `DesktopPttBackend` trait + `PttCapabilityLevel`, platform backends, `PttController` + `AudioTransmitGate`, `PttSanitizer` + `PttCapabilityBadge`, `MissedKeyUpWatchdog`. |
|