edison/chanora
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(traceability): close SRS-200 SAD/SDD coverage gap (P0 audit follow-up)

Browse Source 
A P0 traceability audit per the project's compliance workflow
found exactly one gap across the 162 P0 SRS items:

  * SRS-200 (mouse side buttons as bindable inputs for desktop
    Global PTT) had no dedicated SAD item. The earlier baseline
    matrix folded SRS-200 under the narrative
    `SRS-195..203 -> SAD-071..079` umbrella, which technically
    covered the requirement at the table level but did not give
    SRS-200 a one-to-one SAD source the validator's strict
    discipline expects.

Per the project's gate-check workflow (Case C —
BLOCKED_MISSING_SAD) this commit closes the documentation chain
*before* claiming compliance for the already-merged mouse-side-
button code path:

  * `docs/architecture/sad.md` v0.9.4 — new `SAD-080` sources
    SRS-200, allocates `Audio (Windows / macOS / Linux), Bridge,
    Flutter UI`, and records the cross-platform mouse-side-button
    surface as a software-architecture item. The §27 coverage
    matrix gains a dedicated SRS-200 -> SAD-080 row.
  * `docs/architecture/sdd.md` v0.9.4 — new `SDD-093` sources
    SAD-080. Specifies the `PttInputClass` enum surface
    (`None` / `Keyboard` / `MouseSideButton`), the rebind
    contract on the Windows + macOS backends, the Linux portal's
    pass-through behaviour, and the Flutter
    `PointerEvent.buttons` bitmask capture (back = `0x08`,
    forward = `0x10`). The §11 coverage matrix gains the
    SAD-080 -> SDD-093 row.
  * `docs/governance/traceability-matrix.md` v0.9.4 — the
    `(DEC-026 mouse buttons)` row moves from
    `SAD-072..074 / SDD-082..086` to the dedicated
    `SAD-080 / SDD-093`.
  * `docs/governance/baseline-candidate-validation-report.md`
    v0.9.4 — ID totals advance to 302 / 148 / 203 / 80 / 93;
    direct-layer-rule and undefined-reference counts remain
    zero.
  * `docs/governance/repo-format-validation-report.md` v0.9.4 —
    same ID totals update.

Audit summary
-------------

* 162 P0 SRS items audited.
* 1 SAD-coverage gap (SRS-200) — closed by this commit.
* 0 SDD-coverage gaps (every PTT SAD has explicit SDD coverage;
  the inherited baseline `SAD-032/033` are covered through the
  documented range row, not individually).
* All Priority: P0 software requirements now have a strict
  SRS -> SAD -> SDD chain on file.

Validator output:

```
[OK] SysRS: 302 defined, 0 undefined references
[OK] SysDes: 148 defined, 0 undefined references
[OK] SRS: 203 defined, 0 undefined references
[OK] SAD: 80 defined, 0 undefined references
[OK] SDD: 93 defined, 0 undefined references
[OK] SRS direct SysRS references: 0
[OK] SAD direct SysRS references: 0
[OK] SAD direct SysDes references: 0
[OK] SDD direct SysRS references: 0
[OK] SDD direct SysDes references: 0
[OK] SDD direct SRS references: 0
```

Implementation status
---------------------

The mouse-side-button code was implemented in v1.0.0-rc.4 and
v1.0.0-rc.5 under the (then-implicit) PTT umbrella; the code
already matches the new SDD-093's contract verbatim. This
commit ships **documentation only** — it adds the SAD/SDD/matrix
rows that retroactively justify the existing implementation
under the strict traceability discipline. No code edits, no test
edits.

  * `cargo test --workspace`: 67/67 green (unchanged).
  * `cargo deny check`: advisories ok, bans ok, licenses ok,
    sources ok.
  * `cargo about generate`: zero new warnings (no Cargo.lock
    delta).
  * `flutter analyze`: clean.
  * `tools/validate_docs.py`: all SRS/SAD/SDD coverage and
    direct-layer-rule checks pass.

Outstanding open items remain live verification per
`docs/release/release-readiness-go-nogo-record.md`
(RR-PTT-001..006/008) and the DEC-012 legal review; both are
non-engineering work.
This commit is contained in:
EdisonJwa
2026-05-15 17:02:26 +08:00
parent 03f5d6bca3
commit 63f2901a6a
5 changed files with 49 additions and 6 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/architecture/sad.md
+18 -1
View File
@@ -1355,13 +1355,23 @@ Communication evidence is maintained through change history and baseline approva
- Source SRS: SRS-203
- Verification method: Unit Test, Integration Test
**SAD-080**: The software architecture shall expose a mouse-side-button input class as a first-class member of the cross-platform PTT binding type so the Windows and macOS backends can drive `transmit_active` from `Mouse4` / `Mouse5` events while the Linux GNOME-Wayland portal backend honours whatever input classes the portal's own dialog returns. The bridge surface and the Flutter binding-capture dialog shall carry the same coarse class without ever exposing a raw mouse button id beyond the `PointerEvent.buttons` bitmask on the platform side.
- Status: Baseline Candidate
- Type: Software Architecture Item
- Stage: P0 / MVP
- Allocated to: Audio (Windows / macOS / Linux), Bridge, Flutter UI
- Source SRS: SRS-200
- Verification method: Unit Test, Platform Test, UI Review
## 27. Updated SRS-to-SAD Coverage Matrix
| SRS Range | SAD Coverage |
|---|---|
| SRS-001 through SRS-184 | Covered by inherited SAD baseline `SAD-001` through `SAD-060` |
| SRS-185 through SRS-194 | Covered by `SAD-061` through `SAD-070` |
| SRS-195 through SRS-203 | Covered by `SAD-071` through `SAD-079` |
| SRS-195 through SRS-199, SRS-201 through SRS-203 | Covered by `SAD-071` through `SAD-079` |
| SRS-200 | Covered by `SAD-080` |
## Baseline Candidate 0.9.1 Update
@@ -1383,3 +1393,10 @@ Communication evidence is maintained through change history and baseline approva
| Version | Date | Description |
|---|---|---|
| 0.9.3 | 2026-05-15 | Added desktop PTT software-architecture items SAD-071 through SAD-079: backend isolation behind `DesktopPttBackend` trait, Windows three-rung ladder, macOS two-rung permission-aware ladder, Linux GNOME-Wayland portal ladder, `AudioTransmitGate` object, sanitised `BridgeEvent::PttCapability`, `PttSanitizer` log-sink decorator, UI capability badge with platform-specific explanation, missed-key-up watchdog task. Strict layered sourcing preserved (`SAD -> SRS` only). |
## Baseline Candidate 0.9.4 Update
| Version | Date | Description |
|---|---|---|
| 0.9.4 | 2026-05-15 | Added `SAD-080` to close the SRS-200 coverage gap surfaced by a P0 traceability audit. The earlier baseline matrix folded SRS-200 under the `SRS-195..203 -> SAD-071..079` range without giving it a dedicated SAD item; the new entry restores the strict one-to-many SRS-to-SAD discipline (SRS-200 is now sourced by SAD-080; SAD-080 is in turn covered by the new SDD-093). No other rows mutate; the existing PTT SAD items (071..079) retain their original SRS sources. |
docs/architecture/sdd.md
+17
View File
@@ -1113,6 +1113,15 @@ The registry supports consistency between architecture, detailed design, impleme
- Source SAD: SAD-079
- Verification method: Unit Test, Integration Test
**SDD-093**: `PttInputClass` shall be a Rust enum in `chanora_audio::ptt_backends` with variants `None`, `Keyboard`, and `MouseSideButton`. The enum is the only carrier of the user's bound input class across the audio + bridge + Flutter boundary; its `as_str(&self) -> &'static str` mapping returns the diagnostic-safe label (`""` / `"keyboard"` / `"mouse-side-button"`) consumed by `PttBackendDescriptor::bound_input_class`. The Windows backend ladder and the macOS event-tap backend shall observe the `MouseSideButton` variant on their binding-rebind path and translate it into the platform's native side-button identifier internally; the Linux GNOME-Wayland portal backend shall accept whatever input class the portal returns from `BindShortcuts` and apply the same classifier already documented in `desktop-ptt-architecture.md` §5.3. The Flutter binding-capture dialog shall capture mouse side-button presses through the `PointerEvent.buttons` bitmask (back = `0x08`, forward = `0x10`) and never forward the raw bitmask beyond the dialog — the bridge `set_ptt_binding` call carries only the enum variant.
- Status: Draft
- Type: Software Detailed Design Item
- Stage: P0 / MVP
- Software unit: `PttInputClass`, `WindowsRawInputBackend`, `WindowsHookBackend`, `MacOSEventTapBackend`, `LinuxGnomeWaylandBackend`, `_PttBindingCaptureDialog`
- Source SAD: SAD-080
- Verification method: Unit Test, Platform Test (Windows / macOS / Linux), UI Review
## 11. Updated SAD-to-SDD Coverage Matrix
| SAD Range | SDD Coverage |
@@ -1120,6 +1129,7 @@ The registry supports consistency between architecture, detailed design, impleme
| SAD-001 through SAD-060 | Covered by inherited SDD baseline `SDD-001` through `SDD-070` |
| SAD-061 through SAD-070 | Covered by `SDD-071` through `SDD-080` |
| SAD-071 through SAD-079 | Covered by `SDD-081` through `SDD-092` |
| SAD-080 | Covered by `SDD-093` |
## Baseline Candidate 0.9.1 Update
@@ -1141,3 +1151,10 @@ The registry supports consistency between architecture, detailed design, impleme
| Version | Date | Description |
|---|---|---|
| 0.9.3 | 2026-05-15 | Added desktop PTT detailed design SDD-081 through SDD-092: `DesktopPttBackend` trait, `PttCapabilityLevel` enum, Windows Raw-Input + low-level-hook + Focused implementations, macOS event-tap + Focused implementations, Linux GNOME-Wayland portal + Focused implementations, `PttController`, `AudioTransmitGate`, `PttSanitizer` layer, `PttCapabilityBadge` widget, `MissedKeyUpWatchdog` task. Strict sourcing (`SDD -> SAD` only) preserved. |
## Baseline Candidate 0.9.4 Update
| Version | Date | Description |
|---|---|---|
| 0.9.4 | 2026-05-15 | Added `SDD-093` covering `SAD-080`. `SDD-093` fixes the `PttInputClass` enum surface, the cross-backend rebind contract for `MouseSideButton`, and the Flutter side-button capture path against the `PointerEvent.buttons` bitmask. Strict layered sourcing preserved (`SDD -> SAD` only). |
docs/governance/baseline-candidate-validation-report.md
+3 -2
View File
@@ -26,8 +26,8 @@ chanora-docs-repo-format-v0.9.3
| SysRS | 302 |
| SysDes | 148 |
| SRS | 203 |
| SAD | 79 |
| SDD | 92 |
| SAD | 80 |
| SDD | 93 |
## 4. Undefined Reference Check
@@ -89,3 +89,4 @@ chanora-docs-repo-format-v0.9.3
|---|---|---|
| 0.9.2 | 2026-05-14 | Validation report for Apple App Store Connect upload SDK gate correction, full file update, and coverage check. |
| 0.9.3 | 2026-05-15 | Validation report for desktop Push-to-Talk update: added 7 SysRS / 7 SysDes / 9 SRS / 9 SAD / 12 SDD entries, added `desktop-ptt-architecture.md`, recorded six new owner decisions DEC-023..028; ID totals advance to 302 / 148 / 203 / 79 / 92; direct-layer rule and undefined-reference counts remain zero. |
| 0.9.4 | 2026-05-15 | P0 traceability audit follow-up: added `SAD-080` and `SDD-093` to close the SRS-200 coverage gap surfaced by the audit. ID totals advance to 302 / 148 / 203 / 80 / 93; direct-layer-rule and undefined-reference counts remain zero. No code change in this revision; the existing mouse-side-button support previously implemented under the broader `SRS-195..203 -> SAD-071..079 -> SDD-081..092` umbrella is now tied to the dedicated SAD/SDD pair. |
docs/governance/repo-format-validation-report.md
+3 -2
View File
@@ -37,8 +37,8 @@ chanora-docs-repo-format-v0.9.3
| SysRS | 302 |
| SysDes | 148 |
| SRS | 203 |
| SAD | 79 |
| SDD | 92 |
| SAD | 80 |
| SDD | 93 |
## 5. Undefined Reference Check
@@ -74,3 +74,4 @@ chanora-docs-repo-format-v0.9.3
|---|---|---|
| 0.9.2 | 2026-05-14 | Validated repository-format documentation package and internal filename reference updates. |
| 0.9.3 | 2026-05-15 | Re-validated repository-format after desktop PTT update: added `docs/architecture/desktop-ptt-architecture.md`; ID totals advance to 302 / 148 / 203 / 79 / 92; naming, undefined-reference, and direct-layer-rule counts remain at zero. |
| 0.9.4 | 2026-05-15 | P0 audit follow-up: ID totals advance to 302 / 148 / 203 / 80 / 93 after adding `SAD-080` (sources SRS-200) and `SDD-093` (sources SAD-080). Direct-layer-rule and undefined-reference counts remain zero. |
docs/governance/traceability-matrix.md
+8 -1
View File
@@ -211,7 +211,7 @@ SysRS-296..302
| SysRS-300 (macOS permission-aware) | SysDes-145 | SRS-198 | SAD-073 | SDD-085 |
| SysRS-301 (Linux GNOME-Wayland) | SysDes-145 | SRS-199 | SAD-074 | SDD-086 |
| SysRS-302 (No raw key history) | SysDes-146 | SRS-202 | SAD-077 | SDD-090 |
| (DEC-026 mouse buttons) | SysDes-142, SysDes-145 | SRS-200 | SAD-072..074 | SDD-082..086 |
| (DEC-026 mouse buttons) | SysDes-142, SysDes-145 | SRS-200 | SAD-080 | SDD-093 |
| (DEC-028 missed-key-up watchdog) | SysDes-142, SysDes-144 | SRS-203 | SAD-079 | SDD-092 |
Verification coverage:
@@ -228,3 +228,10 @@ No forbidden direct links introduced: SRS continues to source from SysDes only,
| Version | Date | Description |
|---|---|---|
| 0.9.3 | 2026-05-15 | Added desktop PTT traceability rows covering SysRS-296..302 -> SysDes-142..148 -> SRS-195..203 -> SAD-071..079 -> SDD-081..092 and the verification coverage onto SWE.4 / SWE.5 / SWE.6 / SYS.4. |
## Baseline Candidate 0.9.4 Update
| Version | Date | Description |
|---|---|---|
| 0.9.4 | 2026-05-15 | Corrected SRS-200 traceability row: SAD coverage moves from the narrative `SAD-072..074` annotation to the dedicated `SAD-080`, with SDD coverage in the new `SDD-093`. The change preserves strict layer discipline (SRS-200 -> SAD-080 -> SDD-093). No other rows mutate. |