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.
129 lines
7.9 KiB
Markdown
129 lines
7.9 KiB
Markdown
|
|
# Chanora External Reference Collection
|
|
|
|
**Version:** 0.9.2
|
|
**Status:** Baseline Candidate
|
|
**Language:** English
|
|
**Product:** Chanora
|
|
|
|
**Repo path:** `docs/references/external-references.md` ---
|
|
|
|
## 1. Material 3 and Flutter References
|
|
|
|
| Reference | Purpose |
|
|
|---|---|
|
|
| https://m3.material.io/ | Material 3 design system baseline |
|
|
| https://m3.material.io/foundations/design-tokens/overview | Material 3 design tokens |
|
|
| https://m3.material.io/styles/color/system/how-the-system-works | Material 3 color system |
|
|
| https://m3.material.io/styles/typography | Material 3 typography |
|
|
| https://m3.material.io/foundations/adaptive-design | Material 3 adaptive design |
|
|
| https://m3.material.io/components | Material 3 components |
|
|
| https://docs.flutter.dev/ui/design/material | Material Design in Flutter |
|
|
| https://docs.flutter.dev/ui/widgets/material | Flutter Material widget catalog |
|
|
| https://docs.flutter.dev/release/breaking-changes/material-3-default | Flutter Material 3 default behavior |
|
|
| https://docs.flutter.dev/release/breaking-changes/material-3-migration | Flutter Material 3 migration guidance |
|
|
| https://api.flutter.dev/flutter/material/ThemeData-class.html | Flutter ThemeData API |
|
|
| https://api.flutter.dev/flutter/material/ColorScheme-class.html | Flutter ColorScheme API |
|
|
| https://api.flutter.dev/flutter/material/ThemeExtension-class.html | Flutter ThemeExtension API |
|
|
|
|
## 2. Android and iOS Platform References
|
|
|
|
| Reference | Purpose |
|
|
|---|---|
|
|
| https://developer.android.com/develop/ui/compose/layouts/adaptive/use-window-size-classes | Android window size classes and adaptive layout reference |
|
|
| https://developer.android.com/guide/navigation/custom-back/predictive-back-gesture | Android predictive back behavior |
|
|
| https://developer.android.com/develop/connectivity/bluetooth/bt-permissions | Android Bluetooth permissions |
|
|
| https://developer.apple.com/design/human-interface-guidelines/ | Apple Human Interface Guidelines |
|
|
| https://developer.apple.com/documentation/avfaudio/avaudiosession/category-swift.struct | AVAudioSession category reference |
|
|
|
|
## 3. ASPICE and Requirements / Design Process References
|
|
|
|
| Reference | Purpose |
|
|
|---|---|
|
|
| `Automotive-SPICE-PAM-v40.pdf` | Automotive SPICE process model |
|
|
| https://www.ul.com/sis/resources/process-swe-1 | UL SWE.1 Software Requirements Analysis guidance |
|
|
| https://www.ul.com/sis/resources/process-swe-2 | UL SWE.2 Software Architectural Design guidance |
|
|
| https://www.ul.com/sis/resources/process-swe-3 | UL SWE.3 Software Detailed Design and Unit Construction guidance |
|
|
| https://www.ul.com/sis/resources/process-swe-4 | UL SWE.4 Software Unit Verification guidance |
|
|
| https://www.ul.com/sis/resources/process-swe-5 | UL SWE.5 Software Component Verification and Integration Verification guidance |
|
|
| https://www.ul.com/sis/resources/process-swe-6 | UL SWE.6 Software Verification guidance |
|
|
| https://www.ul.com/sis/insights/system-integration-and-integration-test-sys4-automotive-spice | UL SYS.4 System Integration and Integration Test guidance |
|
|
| https://polarion.code.blog/2021/11/10/swe-2-software-architectural-design/ | Polarion SWE.2 Software Architectural Design notes |
|
|
| https://polarion.code.blog/2022/04/21/swe-3-software-detailed-design-and-unit-construction/ | Polarion SWE.3 Software Detailed Design and Unit Construction notes |
|
|
| https://polarion.code.blog/2023/01/18/swe-4-software-unit-verification/ | Polarion SWE.4 Software Unit Verification notes |
|
|
| https://polarion.code.blog/2023/06/28/swe-5-software-integration-and-integration-test/ | Polarion SWE.5 Software Integration and Integration Test notes |
|
|
| https://polarion.code.blog/2025/06/05/swe-6-software-qualification-test/ | Polarion SWE.6 Software Qualification Test notes |
|
|
| https://polarion.code.blog/2025/08/06/sys-4-system-integration-and-integration-verification-a-spice-4-0/ | Polarion SYS.4 System Integration and Integration Verification notes |
|
|
|
|
## 4. Software Architecture and Design Document References
|
|
|
|
| Reference | Purpose |
|
|
|---|---|
|
|
| https://medium.com/codex/what-goes-in-a-software-architecture-document-e97d808d5cec | Software Architecture Document content and architecture views |
|
|
| https://www.atlassian.com/work-management/knowledge-sharing/documentation/software-design-document | Software Design Document structure, including overview, architecture, data design, interface design, component design, UI design, assumptions, dependencies, and glossary |
|
|
|
|
## 5. Use in Chanora Documentation
|
|
|
|
| Reference category | Applied to |
|
|
|---|---|
|
|
| Material 3 and Flutter | UI/UX guideline, design tokens, component catalog, adaptive layout, SysDes, SRS, SAD, SDD |
|
|
| Android and iOS platform references | Platform behavior guide, SysRS, SysDes, SRS, SAD, SDD |
|
|
| ASPICE references | SysDes, SRS, SAD, SDD, SWE.4, SWE.5, SWE.6, SYS.4, traceability matrix |
|
|
| Software architecture/design document references | SAD v0.3, SDD v0.3 |
|
|
|
|
## 6. Change History
|
|
|
|
| Version | Date | Description |
|
|
|---|---|---|
|
|
| 0.1.0 | 2026-05-14 | Initial reference collection. |
|
|
| 0.2.0 | 2026-05-14 | Added Atlassian software design document reference, UL SWE.2, UL SWE.3, Polarion SWE.2, Polarion SWE.3, and Medium SAD article reference. |
|
|
| 0.3.0 | 2026-05-14 | Added UL and Polarion references for SWE.4, SWE.5, SWE.6, and SYS.4 verification planning. |
|
|
|
|
---
|
|
|
|
## 7. Platform Release Policy Reference Addendum
|
|
|
|
| Reference | Purpose |
|
|
|---|---|
|
|
| Apple Developer - Upcoming Requirements | Apple App Store Connect SDK submission requirement; current baseline uses Xcode 26+ and iOS 26 / iPadOS 26 SDK+ on or after 2026-04-28 unless newer Apple policy applies. |
|
|
| Flutter supported platforms | Runtime platform support baseline; current decision uses iOS 13+ and Android API 24+ unless project constraints raise them. |
|
|
| Google Play target API level requirements | Android target SDK release gate; target the Google Play-required API level on upload date. |
|
|
|
|
|
|
## 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. |
|
|
|
|
---
|
|
|
|
## 8. Apple SDK Gate Reference Correction
|
|
|
|
| Reference | Purpose |
|
|
|---|---|
|
|
| https://developer.apple.com/news/upcoming-requirements/?id=02032026a | Apple Upcoming Requirements page defining the App Store Connect upload build gate: since April 28, 2026, uploaded apps must be built with Xcode 26 or later using the applicable platform 26 SDK or later. |
|
|
|
|
|
|
## 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. |
|
|
|
|
|
|
## Desktop Push-to-Talk Reference Addendum (Baseline Candidate 0.9.3)
|
|
|
|
| Area | Reference (informative) |
|
|
|---|---|
|
|
| Windows input APIs | Microsoft Windows Raw Input documentation (`RegisterRawInputDevices`, `WM_INPUT`); Windows low-level keyboard / mouse hook documentation (`WH_KEYBOARD_LL`, `WH_MOUSE_LL`). |
|
|
| macOS event tap | Apple Core Graphics event-tap documentation (`CGEventTapCreate`, `kCGEventTapDisabledByTimeout`); IOKit `IOHIDCheckAccess` for permission state. |
|
|
| Linux Wayland global shortcuts | freedesktop.org XDG portal documentation for the `org.freedesktop.portal.GlobalShortcuts` interface. |
|
|
| Permission-aware input on macOS | Apple privacy / TCC documentation for Input Monitoring and Accessibility entitlements. |
|
|
|
|
Reviewers should consult the current upstream version of each reference because OS surfaces change over time; the references above identify the relevant area rather than pinning a specific version.
|
|
|
|
| Version | Date | Description |
|
|
|---|---|---|
|
|
| 0.9.3 | 2026-05-15 | Added desktop-PTT external references covering Windows Raw Input + hook documentation, macOS event-tap + IOHIDCheckAccess, Linux GlobalShortcuts portal, and macOS Input Monitoring / Accessibility entitlements. |
|