edison/chanora
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
33d80894d08cc6df57e64c41a3a2681a8ecf6a26
chanora/docs/references/external-references.md
T
EdisonJwa 02ffadfa52 docs(ptt): land Baseline Candidate v0.9.3 — capability-based desktop PTT 
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.
2026-05-15 14:51:22 +08:00

7.9 KiB
Raw Blame History

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.
Reference in New Issue View Git Blame Copy Permalink