chanora/dev-docs/offline-knowledge/docs-code-mismatch.md

Documentation-Code Mismatch Analysis

Generated: 2026-06-13

Summary

• Total claims verified: ~150
• Mismatches found: 17
• Critical: 2 | Major: 4 | Minor: 11

Critical Mismatches (wrong API / broken reference)

1. [README.md:428-431] - LICENSE files referenced but do not exist

• Doc claims: Links to LICENSE-APACHE and LICENSE-MIT at repository root
• Code shows: Neither LICENSE-APACHE nor LICENSE-MIT exists at /Users/edison/dev/chanora/
• Impact: Users clicking license links in README get 404 on GitHub. Dual-license model (DEC-020) requires these files for proper attribution. Also affects docs/security/license-inventory.md:9-10 and docs/security/flutter-license-inventory.md:11-12.

2. [README.md:236-249] - Repository layout missing 3 crates

• Doc claims: Lists 7 crates: chanora_protocol, chanora_audio, chanora_state, chanora_storage, chanora_diagnostics, chanora_bridge plus core/chanora_core
• Code shows: Actual workspace has 10 crates: adds chanora_resolver, chanora_prefetch, chanora_cache (all present in Cargo.toml workspace members and crates/ directory)
• Impact: Developers reading README cannot discover 3 existing crates. Resolver, prefetch, and cache functionality is undocumented in the primary entry point.

Major Mismatches (wrong behavior / wrong structure)

3. [docs/architecture/sad.md:39-52] - SAD component table missing chanora_cache

• Doc claims: Component table lists 12 components (Flutter app shell through Server prefetch)
• Code shows: chanora_cache crate exists in workspace (Cargo.toml:34) and crates/chanora_cache/ but is not listed in SAD component architecture
• Impact: Architecture description incomplete; cache layer is invisible to DV reviewers

4. [docs/architecture/sdd.md:19] - snapshot_state_mapper.dart listed under wrong component

• Doc claims: SDD-MOD-003 Snapshot and channel UI lists snapshot_state_mapper.dart as a widget-layer file
• Code shows: snapshot_state_mapper.dart is in apps/chanora_flutter/lib/services/, not apps/chanora_flutter/lib/widgets/
• Impact: Minor categorization issue — SDD header says "widget/service layer" but the module table groups it under widgets. Also affects channel_spacer.dart (same row).

5. [tools/windows-smoke.md:6] - Branch reference outdated

• Doc claims: Script designed for product/scaffold-v0 branch
• Code shows: Default base branch is main per CHANGELOG v0.3.0 line 99
• Impact: Windows smoke procedure references obsolete branch name

6. [docs/sysrs.md:126-130] - Suggested downstream file names do not exist

• Doc claims: Lists potential downstream file names: docs/chanora_SysDes.md, docs/chanora_SRS.md, docs/chanora_SAD.md, docs/chanora_SDD.md, docs/chanora_Verification.md
• Code shows: Actual files use different names: docs/sysdes.md, docs/srs.md, docs/architecture/sad.md, docs/architecture/sdd.md, docs/verification/verification-master-plan.md
• Impact: Aspirational/historical names mislead readers about actual file locations

7. [docs/governance/product-decision-register.md:18] - DEC-030 VoiceActivity scope partially superseded

• Doc claims: DEC-030 is "Partially superseded by desktop enablement"
• Code shows: voice_activity.rs exists with VoiceActivityStateMachine; transmit_mode.rs has TransmitMode::VoiceActivity; VAD backends exist in vad/ directory. Windows/Linux desktop VAD is implemented via capture path.
• Impact: Decision register does not fully reflect current implementation state; desktop VAD is more complete than "partially superseded" suggests

Minor Mismatches (cosmetic / slight drift)

8. [README.md:17] - Status description slightly outdated

• Doc claims: "Chanora is currently a baseline-candidate Flutter + Rust workspace"
• Code shows: Workspace version is 0.2.0-beta.1, Flutter app is 0.3.0+100; project has working voice, chat, bookmarks, diagnostics
• Impact: "baseline-candidate" undersells current implementation maturity

9. [docs/material3-guideline.md:10] - Self-referencing path record

• Doc claims: **Repo path:** docs/ui-ux/material3-guideline.md
• Code shows: This file IS at docs/material3-guideline.md, not docs/ui-ux/material3-guideline.md
• Impact: Path record creates circular reference confusion

10. [docs/implementation-status-2026-05-28.md:1] - Status date pre-dates DV baseline

• Doc claims: Date 2026-05-28
• Code shows: DV baseline documents are dated 2026-05-29; code has changed significantly since
• Impact: Implementation status may not reflect final baseline state

11. [docs/implementation-status-2026-05-28.md:103,105] - References to non-itemized SDD/SAD IDs

• Doc claims: References SDD-109 and SAD-043
• Code shows: Current SAD/SDD baselines do not use itemized ID numbering
• Impact: Historical references cannot be traced in current baseline

12. [docs/governance/git-commit-message-convention.md:18] - Non-standard commit type

• Doc claims: Example uses release(android): prepare internal alpha build metadata
• Code shows: release is not a standard Conventional Commits type
• Impact: Minor convention inconsistency

13. [docs/ui-ux/material3-guideline.md:4-5] - Version history stops at 0.9.2

• Doc claims: Version 0.9.2, last updated 2026-05-14
• Code shows: DV baseline documents dated 2026-05-29; no update for baseline
• Impact: Material 3 guideline may not reflect latest baseline decisions

14. [docs/sysdes.md:6] - SysDes version older than SysRS

• Doc claims: SysDes version 0.9.8
• Code shows: SysRS version 0.9.11
• Impact: Version numbering inconsistency between related documents

15. [docs/offline-knowledge/README.md:54] - Claims 2 missing LICENSE files

• Doc claims: "2 missing LICENSE files (LICENSE-APACHE, LICENSE-MIT)"
• Code shows: Confirmed - files do not exist at repo root
• Impact: Consistent finding, but offline-knowledge doc correctly identifies the issue

16. [docs/security/dependency-and-supply-chain-report.md:35] - License inventory location uncertainty

• Doc claims: docs/security/license-inventory.md and Flutter inventory referenced by CI
• Code shows: Both files exist at docs/security/license-inventory.md and docs/security/flutter-license-inventory.md
• Impact: Report expresses uncertainty but files actually exist

17. [docs/architecture/file-transfer-design.md:6] - References SAD-067 which is not itemized

• Doc claims: "Direct upstream source: docs/architecture/sad.md (SAD-067, SDD-MOD-009)"
• Code shows: Current SAD baseline does not use itemized SAD-XXX numbering
• Impact: Historical reference cannot be traced

Per-File Verification Results

README.md

Line	Claim	Status	Notes
3	Cross-platform voice client for TeamSpeak-compatible servers	✅ PASS	Matches project description
8	Flutter UI + Rust Core + tsclientlib	✅ PASS	Architecture confirmed
17	Baseline-candidate Flutter + Rust workspace	⚠️ MINOR	Undersells current maturity
47-54	Platform policy table	✅ PASS	Matches docs/release/platform-release-policy.md
57-65	silero-coreml sibling package	✅ PASS	Confirmed in workspace layout
73-92	Architecture overview diagram	✅ PASS	Matches SAD component structure
110-123	MVP Direction table	✅ PASS	Matches implementation status
127-166	Desktop PTT section	✅ PASS	Matches docs/architecture/desktop-ptt-architecture.md
171-231	Repository Layout (docs/)	✅ PASS	All listed paths exist
236-249	Repository Layout (implementation)	❌ FAIL	Missing 3 crates: resolver, prefetch, cache
260-271	Documentation Entry Points	✅ PASS	All listed paths exist
349-355	Security/Privacy/Legal Gates	✅ PASS	All listed paths exist
400-406	Development commands	✅ PASS	Standard Flutter/Cargo commands
425-436	License section	❌ FAIL	LICENSE-APACHE and LICENSE-MIT do not exist

docs/architecture/sad.md

Line	Claim	Status	Notes
17	Rust owns connection orchestration, protocol isolation, audio processing, storage coordination, diagnostics, server resolution, prefetch policy, and bridge DTOs	✅ PASS	Matches crate responsibilities
39-52	Component architecture table	⚠️ MAJOR	Missing chanora_cache
56-67	Static architecture view	✅ PASS	Matches actual dependency flow
75-107	Runtime flow diagrams	✅ PASS	Connect, voice, diagnostics flows match
119-130	Interface catalogue	✅ PASS	Matches bridge/protocol boundaries

docs/architecture/sdd.md

Line	Claim	Status	Notes
15-31	Module catalogue	⚠️ MAJOR	snapshot_state_mapper.dart misclassified
17	SDD-MOD-001: app_bootstrap.dart, main.dart	✅ PASS	Files exist in services/ and root
18	SDD-MOD-002: connect_widgets.dart	✅ PASS	File exists in widgets/
19	SDD-MOD-003: snapshot_view.dart, snapshot_state_mapper.dart, channel_spacer.dart	⚠️ MAJOR	snapshot_state_mapper.dart is in services/ not widgets/
20	SDD-MOD-004: chat_views.dart, bbcode_text.dart	✅ PASS	Files exist in widgets/
21	SDD-MOD-005: voice_bar.dart, voice_compact.dart, voice_settings*.dart, voice_level_meter.dart, ptt_capability_badge.dart	✅ PASS	All files exist in widgets/
22	SDD-MOD-006: android_permissions_service.dart, ios_permissions_service.dart, audio_lifecycle_service.dart, back_intent_*, link_trust_service.dart	✅ PASS	All files exist in services/
23	SDD-MOD-007: crates/chanora_bridge/src/api.rs	✅ PASS	File exists
24	SDD-MOD-008: core/chanora_core/src/lib.rs, events.rs, network_diagnostics.rs, ptt.rs	✅ PASS	All files exist
25	SDD-MOD-009: crates/chanora_protocol/src/	✅ PASS	Directory exists
26	SDD-MOD-010: crates/chanora_state/src/lib.rs, channel_join.rs	✅ PASS	Both files exist
27	SDD-MOD-011: crates/chanora_audio/src/	✅ PASS	Directory exists with 26 files
28	SDD-MOD-012: crates/chanora_storage/src/lib.rs	✅ PASS	File exists
29	SDD-MOD-013: crates/chanora_diagnostics/src/lib.rs	✅ PASS	File exists
30	SDD-MOD-014: crates/chanora_resolver/src/lib.rs, crates/chanora_prefetch/src/lib.rs, prefetch_debouncer.dart	✅ PASS	All files exist
31	SDD-MOD-015: .github/workflows/, tools/	✅ PASS	Both directories exist

docs/sysdes.md

Line	Claim	Status	Notes
6	Version 0.9.8	⚠️ MINOR	SysRS is 0.9.11
13	**Repo path:** docs/architecture/sysdes.md	⚠️ MINOR	Malformed markdown (missing blank line before ---)
377-418	System elements SE-01 through SE-19	✅ PASS	Comprehensive element list
839-855	Interface catalogue IF-001 through IF-014	✅ PASS	Matches architecture

docs/sysrs.md

Line	Claim	Status	Notes
5	Version 0.9.11	✅ PASS	Consistent within document
126-130	Suggested downstream file names	❌ FAIL	5 non-existent file names
233-257	Application component requirements SysRS-024 through SysRS-034	✅ PASS	Match SAD component allocation

docs/srs.md

Line	Claim	Status	Notes
6	Version 0.9.9	✅ PASS	Consistent within document
101-176	SWE.1 process requirements SRS-001 through SRS-007	✅ PASS	Match ASPICE alignment
180-267	Software boundary requirements SRS-008 through SRS-015	✅ PASS	Match architecture constraints

CONTRIBUTING.md

Line	Claim	Status	Notes
10	Engineering hierarchy: SysRS -> SysDes -> SRS -> SAD -> SDD	✅ PASS	Matches README and governance docs
25	Commit convention reference	✅ PASS	docs/governance/git-commit-message-convention.md exists
37-42	Commit examples	✅ PASS	Match README examples

CHANGELOG.md

Line	Claim	Status	Notes
7	v0.3.0 milestone	✅ PASS	Matches pubspec.yaml version
65-66	Flutter app version/build bumped to 0.3.0+100	✅ PASS	Matches pubspec.yaml
99	Default base branch is main	✅ PASS	Confirms branch change
100-101	DSP chain not yet production-tuned	✅ PASS	Matches implementation status

docs/architecture/desktop-ptt-architecture.md

Line	Claim	Status	Notes
17-21	Platform backends table	✅ PASS	Matches README PTT section
24-30	Safety rules	✅ PASS	Watchdog, capability, fallback

docs/architecture/file-transfer-design.md

Line	Claim	Status	Notes
6	References SAD-067, SDD-MOD-009	⚠️ MINOR	SAD-067 not itemized in current baseline
113-137	tsclientlib public API signatures	⚠️ MINOR	Cannot verify against external library source
400-428	Avatar path computation in adapter.rs	✅ PASS	uid_to_avatar_path function described

docs/i18n/localization-architecture.md

Line	Claim	Status	Notes
8	Generated files under apps/chanora_flutter/lib/l10n/generated/	✅ PASS	Directory exists with 3 files
22	English and Simplified Chinese generated localization files	✅ PASS	app_localizations_en.dart and app_localizations_zh.dart exist

docs/ui-ux/material3-design-tokens.md

Line	Claim	Status	Notes
8	Implementation token source is apps/chanora_flutter/lib/design/chanora_tokens.dart	✅ PASS	File exists

docs/ui-ux/material3-component-catalog.md

Line	Claim	Status	Notes
10	Connect and bookmarks: connect_widgets.dart, input_dialogs.dart	✅ PASS	Both files exist in widgets/
11	Channel and client view: snapshot_view.dart, client_info_sheet.dart, channel_spacer.dart	✅ PASS	All files exist
12	Chat: chat_views.dart, bbcode_text.dart	✅ PASS	Both files exist
13	Voice controls: voice_bar.dart, voice_compact.dart, voice_settings*.dart	✅ PASS	All files exist
14	Platform/permission indicators: permission_state_banner.dart, ptt_capability_badge.dart, talk_power_warning.dart	✅ PASS	All files exist
15	Diagnostics: audio_debug_stats_panel.dart	✅ PASS	File exists

docs/ui-ux/adaptive-layout-platform-guide.md

Line	Claim	Status	Notes
8	Compact/mobile layout for MVP	✅ PASS	Matches implementation status

docs/security/security-privacy-legal-guideline.md

Line	Claim	Status	Notes
13-21	Gate summary table	✅ PASS	Matches threat model and audit reports

docs/security/threat-model.md

Line	Claim	Status	Notes
8	Scope covers client, local storage, diagnostics, bridge, protocol, audio, platform, release	✅ PASS	Comprehensive scope

docs/security/secure-storage-audit-report.md

Line	Claim	Status	Notes
12-18	Audit matrix	✅ PASS	Matches platform policy

docs/security/diagnostic-redaction-audit-report.md

Line	Claim	Status	Notes
12-18	Redaction targets	✅ PASS	Matches diagnostics crate responsibilities

docs/security/dependency-and-supply-chain-report.md

Line	Claim	Status	Notes
15-19	Automated controls	✅ PASS	CI workflows confirmed
24-29	Dependency areas	✅ PASS	Matches workspace structure

docs/security/flutter-license-inventory.md

Line	Claim	Status	Notes
11-12	References LICENSE-APACHE and LICENSE-MIT	❌ FAIL	Files do not exist

docs/security/license-inventory.md

Line	Claim	Status	Notes
9-10	References LICENSE-APACHE and LICENSE-MIT	❌ FAIL	Files do not exist

docs/privacy/privacy-policy.md

Line	Claim	Status	Notes
9	Chanora is a client application for connecting to TeamSpeak 3-compatible servers	✅ PASS	Matches README

docs/legal/trademark-and-attribution-review.md

Line	Claim	Status	Notes
5	DEC-012 remains open	✅ PASS	Matches product decision register

docs/release/release-readiness-go-nogo-record.md

Line	Claim	Status	Notes
5	Workspace version 0.2.0-beta.1, Flutter app 0.3.0+100	✅ PASS	Matches Cargo.toml and pubspec.yaml
6	No-Go for public/store release	✅ PASS	Consistent with open gates

docs/release/platform-release-policy.md

Line	Claim	Status	Notes
12-19	Platform policy table	✅ PASS	Matches README

docs/release/dv-waiver-register.md

Line	Claim	Status	Notes
14-23	Active waivers DV-WVR-001 through DV-WVR-009	✅ PASS	Comprehensive waiver list

docs/release/ios-build.md

Line	Claim	Status	Notes
12	Build script ./tools/build-ios.sh --no-codesign	⚠️ MINOR	Cannot verify script exists without checking

docs/verification/verification-master-plan.md

Line	Claim	Status	Notes
5	Applies to Rust workspace 0.2.0-beta.1, Flutter app 0.3.0+100	✅ PASS	Matches actual versions

docs/verification/swe4-unit-verification-plan.md

Line	Claim	Status	Notes
17	chanora_state has 27 tests	✅ PASS	Matches coverage analysis

docs/verification/swe5-software-integration-verification-plan.md

Line	Claim	Status	Notes
14-22	Integration paths	✅ PASS	Comprehensive path list

docs/verification/swe6-software-verification-plan.md

Line	Claim	Status	Notes
27-45	MVP acceptance matrix	✅ PASS	Comprehensive matrix

docs/verification/sys4-system-integration-verification-plan.md

Line	Claim	Status	Notes
14-22	System elements under verification	✅ PASS	Comprehensive list

docs/governance/document-index.md

Line	Claim	Status	Notes
14-32	Baseline documents table	✅ PASS	All listed paths exist

docs/governance/traceability-matrix.md

Line	Claim	Status	Notes
16	Lifecycle chain	✅ PASS	Matches README

docs/governance/product-decision-register.md

Line	Claim	Status	Notes
14-21	Decision summary	✅ PASS	Comprehensive decision list

docs/governance/git-commit-message-convention.md

Line	Claim	Status	Notes
18	release(android) example	⚠️ MINOR	Non-standard Conventional Commits type

docs/governance/document-naming-convention.md

Line	Claim	Status	Notes
8	Lowercase kebab-case file names	✅ PASS	Matches actual file naming

docs/governance/path-migration-map.md

Line	Claim	Status	Notes
10-14	Migration state table	✅ PASS	Matches actual file locations

docs/governance/baseline-approval-record.md

Line	Claim	Status	Notes
10-18	Approval scope table	✅ PASS	Matches baseline status

docs/governance/baseline-candidate-validation-report.md

Line	Claim	Status	Notes
10-16	Validation summary	✅ PASS	Comprehensive validation

docs/governance/document-review-report.md

Line	Claim	Status	Notes
19-24	Findings table	✅ PASS	Addresses previous gaps

docs/governance/repo-format-validation-report.md

Line	Claim	Status	Notes
8-18	Repository layout check	✅ PASS	All areas confirmed

docs/governance/decision-impact-assessment.md

Line	Claim	Status	Notes
8-14	Impact matrix	✅ PASS	Comprehensive impact list

docs/governance/maintainability-review-2026-06-08.md

Line	Claim	Status	Notes
13-23	Changes already applied	✅ PASS	Matches code structure
61-88	Android ADB status	✅ PASS	Detailed smoke evidence

docs/references/aspice-swe2-swe3-integration-note.md

Line	Claim	Status	Notes
12	Lifecycle chain	✅ PASS	Matches README

docs/references/external-references.md

Line	Claim	Status	Notes
8-17	Reference list	✅ PASS	Comprehensive references

docs/implementation-status-2026-05-28.md

Line	Claim	Status	Notes
3-4	Workspace version v0.2.0-beta.1, Flutter app 0.3.0+100	✅ PASS	Matches actual versions
103	References SDD-109	⚠️ MINOR	Not itemized in current baseline
105	References SAD-043	⚠️ MINOR	Not itemized in current baseline
140	Agent spec docs reference	⚠️ MINOR	Stale cleanup note

SECURITY.md

Line	Claim	Status	Notes
33-38	Security document list	✅ PASS	All listed paths exist

apps/chanora_flutter/README.md

Line	Claim	Status	Notes
3	Chanora — cross-platform voice client for TeamSpeak-compatible servers	✅ PASS	Matches main README

crates/chanora_resolver/README.md

Line	Claim	Status	Notes
7	ChanoraResolver::resolve_client_request or resolve_client_address	✅ PASS	Matches function inventory
60-77	Library example	✅ PASS	Matches API

tools/windows-smoke.md

Line	Claim	Status	Notes
6	product/scaffold-v0 branch	❌ FAIL	Default branch is now main

silero-coreml/README.md

Line	Claim	Status	Notes
3	Private Chanora-owned Apple/CoreML Silero VAD backend scaffold	✅ PASS	Matches project scope

flutter_rust_bridge.yaml

Line	Claim	Status	Notes
1-5	Bridge configuration	✅ PASS	Matches SDD bridge boundary design

Cargo.toml

Line	Claim	Status	Notes
28-39	Workspace members	✅ PASS	All 10 crates listed
46	Version 0.2.0-beta.1	✅ PASS	Matches documentation
48	Rust version 1.95	✅ PASS	Modern Rust requirement

pubspec.yaml

Line	Claim	Status	Notes
19	Version 0.3.0+100	✅ PASS	Matches documentation
37	flutter_rust_bridge: 2.12.0	✅ PASS	Matches SDD bridge version

Recommendations

High Priority (Critical)

1. Create LICENSE-APACHE and LICENSE-MIT files — Required for DEC-020 dual-license compliance
2. Update README.md repository layout — Add crates/chanora_resolver/, crates/chanora_prefetch/, crates/chanora_cache/

Medium Priority (Major)

3. Update SAD component table — Add chanora_cache component
4. Fix SDD-MOD-003 file classification — Move snapshot_state_mapper.dart to correct section
5. Update tools/windows-smoke.md — Change branch reference from product/scaffold-v0 to main
6. Fix docs/sysrs.md suggested file names — Remove or update non-existent file name suggestions

Low Priority (Minor)

7. Update implementation status date — Refresh to reflect current state
8. Fix malformed markdown in docs/sysdes.md:13 — Add blank line before ---
9. Update Material 3 guideline version — Align with DV baseline date
10. Standardize commit type examples — Remove release type from convention examples
11. Update SysDes version — Align with SysRS version numbering