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

Review: Documentation-Code Mismatch Analysis

Reviewer: opencode (automated) Reviewed document: docs/offline-knowledge/docs-code-mismatch.md Date: 2026-06-13

Verdict: MOSTLY ACCURATE — 2 errors found, 3 mismatches missed

The report is well-structured and the majority of findings are verified. However, there are factual errors in 2 findings, 3 additional mismatches were missed, and severity classifications need adjustment in 2 cases.

---

1. Critical/Major Verification (5 checked)

Critical #1 — LICENSE files missing: CONFIRMED

Root directory listing confirms neither LICENSE-APACHE nor LICENSE-MIT exists. README lines 428-431 link to them. docs/security/license-inventory.md:9-10 and docs/security/flutter-license-inventory.md:11-12 also reference them. Severity (Critical) is appropriate — broken links in README and legal compliance gap.

Critical #2 — README missing 3 crates: CONFIRMED

README lines 236-249 list 6 crates + core/chanora_core. Cargo.toml:28-39 workspace members list 10 crates including chanora_resolver, chanora_prefetch, chanora_cache. Severity (Critical) is appropriate — primary discovery entry point is incomplete.

Major #3 — SAD missing chanora_cache: CONFIRMED

docs/architecture/sad.md:39-52 lists 12 components. chanora_cache is absent despite being a workspace member (Cargo.toml:34). Severity (Major) is appropriate.

Major #4 — snapshot_state_mapper.dart classification: PARTIALLY INCORRECT

The report claims snapshot_state_mapper.dart is "listed as a widget-layer file" but the SDD (docs/architecture/sdd.md:19) actually says upstream is "Flutter widget/service layer" — acknowledging it spans both. The file IS in services/, not widgets/, so there is a mismatch, but the report overstates it by ignoring the "service" qualifier. Severity should be downgraded from Major to Minor. Also, the report missed that channel_spacer.dart (same SDD-MOD-003 row) is also in services/, not widgets/ — same issue, not flagged.

Major #5 — windows-smoke.md branch reference: CONFIRMED

tools/windows-smoke.md:5 says product/scaffold-v0. CHANGELOG.md:99 confirms "Default base branch is main (previously product/scaffold-v0)". Severity (Major) is appropriate — procedure references obsolete branch.

---

2. Minor Verification (3 checked)

Minor #9 — material3-guideline self-referencing path: CONFIRMED but description misleading

docs/material3-guideline.md:10 says **Repo path:** docs/ui-ux/material3-guideline.md. The file IS at docs/material3-guideline.md. However, docs/ui-ux/material3-guideline.md is a redirect stub that points to the canonical file — not a "circular reference confusion" as the report claims. It's a documented migration artifact. Severity (Minor) is appropriate.

Minor #10 — implementation-status date pre-dates DV baseline: CONFIRMED

docs/implementation-status-2026-05-28.md:1 is dated 2026-05-28. docs/governance/git-commit-message-convention.md:4 is dated 2026-05-29 (DV baseline date). Severity (Minor) is appropriate.

Minor #12 — Non-standard commit type release: CONFIRMED

docs/governance/git-commit-message-convention.md:18 uses release(android). Standard Conventional Commits types are: feat, fix, docs, style, refactor, perf, test, build, ci, chore, revert. release is non-standard. Severity (Minor) is appropriate — it's a project convention extension, not a broken reference.

---

3. Spot-Check: 3 Random Doc Files vs Referenced Code

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

• Claim (line 8): Token source is apps/chanora_flutter/lib/design/chanora_tokens.dart
• Actual: File exists at that path. PASS — no mismatch found.

docs/i18n/localization-architecture.md

• Claim (line 8): Generated files under apps/chanora_flutter/lib/l10n/generated/
• Claim (line 22): English and Simplified Chinese localization files present
• Actual: Directory exists with app_localizations.dart, app_localizations_en.dart, app_localizations_zh.dart. PASS — no mismatch found.

docs/architecture/desktop-ptt-architecture.md

• Claim (lines 17-21): Platform backends table (Windows Raw Input, macOS Event Tap, Linux portal)
• Claim (lines 24-30): Safety rules (watchdog, capability, fallback)
• Actual: Claims are descriptive/architectural, not file-path references. Cannot verify runtime behavior from static analysis, but no obvious code contradiction. PASS — no mismatch found.

---

4. Severity Classification Review

#	Claim	Report Severity	Correct?	Notes
1	LICENSE files missing	Critical	Yes	Legal/compliance gap + broken links
2	README missing 3 crates	Critical	Yes	Primary discovery entry incomplete
3	SAD missing chanora_cache	Major	Yes	Architecture doc incomplete
4	snapshot_state_mapper.dart	Major	No — should be Minor	SDD already says "widget/service layer"; overclaimed
5	windows-smoke branch	Major	Yes	Procedure references obsolete branch
6	sysrs.md suggested names	Major	Yes	5 non-existent file paths
7	DEC-030 partially superseded	Major	Borderline	Code has full VAD impl; "partially superseded" undersells it. Could be Major or Minor.
8	baseline-candidate description	Minor	Yes	Cosmetic underselling
9	material3 self-ref path	Minor	Yes	Redirect stub, not circular
10	implementation-status date	Minor	Yes	Date drift
11	SDD/SAD non-itemized IDs	Minor	Yes	Historical references
12	Non-standard commit type	Minor	Yes	Convention extension
13	Material3 version stops at 0.9.2	Minor	Yes	Version drift
14	SysDes version older than SysRS	Minor	Yes	Version inconsistency
15	offline-knowledge LICENSE claim	Minor	Yes	Consistent finding
16	License inventory uncertainty	Minor	Yes	Files exist; report was uncertain
17	file-transfer SAD-067 ref	Minor	Yes	Historical reference
18	verification-master-plan versions	Minor	N/A	Report itself says "no mismatch" — should not be listed as a mismatch

Issue with #18: The report lists this as a mismatch but the notes say "Version claims match actual code (no mismatch)." This is a false positive — it should be removed from the mismatch list or moved to the "verified correct" section.

---

5. Missed Mismatches

M1. channel_spacer.dart also in wrong directory (SDD-MOD-003)

• Doc: docs/architecture/sdd.md:19 lists channel_spacer.dart under SDD-MOD-003 alongside snapshot_state_mapper.dart
• Code: channel_spacer.dart is at apps/chanora_flutter/lib/services/channel_spacer.dart, not in widgets/
• Severity: Minor (same as snapshot_state_mapper — both are in services/)
• Why missed: Report focused on snapshot_state_mapper.dart but didn't check the other file in the same row

M2. chanora_cache missing from dependency-and-supply-chain-report.md

• Doc: docs/security/dependency-and-supply-chain-report.md:25 lists 9 Rust workspace crates
• Code: Cargo.toml has 10 workspace members (includes chanora_cache)
• Severity: Minor — the dependency report's crate list is incomplete, same pattern as the SAD table
• Why missed: Report checked SAD for this pattern but not the dependency report

M3. SAD architectural scope description omits cache

• Doc: docs/architecture/sad.md:17 says "Rust owns connection orchestration, protocol isolation, audio processing, storage coordination, diagnostics, server resolution, prefetch policy, and bridge DTOs"
• Code: chanora_cache crate exists for avatar/icon blob caching — not mentioned in scope description
• Severity: Minor — descriptive text omission, not a structural table gap
• Why missed: Report checked the component table but not the prose description

---

6. Additional Observations

1. Mismatch #18 is a false positive. It's listed as a mismatch but the notes confirm versions match. Remove it.

2. Mismatch #4 overclaims. The SDD uses "Flutter widget/service layer" as upstream, not "Flutter widget layer." The report's characterization is inaccurate. The file IS in services/ so there's still a mismatch, but it's less severe than described.

3. Mismatch #7 (DEC-030) severity is borderline. The code has VoiceActivityStateMachine, TransmitMode::VoiceActivity, and VAD backends in vad/. The doc says "Partially superseded by desktop enablement." This could be argued as Major (policy doc doesn't reflect implementation completeness) or Minor (it does say "partially" which leaves room). Current Major classification is defensible but the report should note the ambiguity.

4. The dependency report has the same chanora_cache omission as the SAD. This is a consistent pattern across multiple docs — the cache crate was added to the workspace after these documents were baselined.

---

Summary

Category	Count
Verified correct	15 of 18
Factual errors	2 (#4 overclaims, #18 false positive)
Missed mismatches	3
Severity adjustments needed	1 (#4: Major → Minor)
False positives to remove	1 (#18)

Overall assessment: The mismatch analysis is ~83% accurate. The core findings (LICENSE files, missing crates in README, SAD table gaps) are solid and well-evidenced. The report would benefit from removing mismatch #18, downgrading #4, and adding the 3 missed findings.