docs(architecture): audit Desktop and frontend group against implementation

[ggbdpq]

Summary

Audits the Desktop and frontend group (7 documents) from #3522 against the current implementation. One dated review gained a drift note; everything else verified clean. The six hand-maintained documents gained the standard frontmatter with last_verified, while the generated surface-file inventory is left byte-identical to its base revision.

• docs/frontend-css-governance.md + .zh-CN.md — conventions hold; every cited path resolves (styles.css entry file, styles/**, maka-tokens.css, reference-shell.css, styles/settings/**); the pair stays in lockstep (7 sections each, translation_status: synced).
• docs/astryx-surface-file-inventory.md — verified with the repository's own check: npm run astryx:surface-inventory reports coverage ok (249 files, 1 exclusion). The document itself stays untouched: it is generated by scripts/generate-astryx-surface-inventory.mjs, and the check compares the file byte-for-byte with regenerated output, so hand-added frontmatter on it fails CI (caught by the first CI run; the file is restored to its base revision here).
• docs/astryx-alignment-inventory.md — already carries its own "superseded for file-level coverage" pointer to the file inventory; the family-level wiki map stands as written.
• docs/astryx-full-surface-audit.md (2026-08-09) and docs/settings-astryx-deep-review.zh-CN.md (2026-08-03) — self-dated review records; spot-checked cited paths (settings-section.tsx, styles/settings/rows.css, overlay/shell files) still resolve.
• docs/frontend-architecture-astryx-review-2026-08-09.md — a review pinned to HEAD 0ad579d33. Its citations are historical anchors and stay as written, but a status note now records what moved since: the workbar lives under apps/desktop/src/renderer/features/workbar/ (session-workbar.tsx / session-workbar-tabs.ts / use-shell-layout.ts no longer sit at their cited paths) and the Astryx core patch is now patches/@astryxdesign+core+0.5.2.patch. Every other cited filename was re-checked against the current tree by basename.

Verification

Claim	Command / route	Result
Surface inventory currency	npm run astryx:surface-inventory	exit 0, 249 files covered
Generated inventory untouched	npm run astryx:surface-inventory on the branch	exit 0, byte-identical to base
Path references across all 7 docs	scripted bulk check (51+ path-like names) + basename re-check	all resolve or are marked historical
CSS governance pair lockstep	heading comparison	7 sections each
Review record HEAD	git cat-file -t 0ad579d33	resolves
Format / headers	npm run format:check / npm run check:asf-headers	exit 0 / changed files pass

AI use

Prepared with ZCode (GLM-5.3-Flash): read all seven documents, bulk-verified path references, ran the repository's own inventory check, and added the frontmatter to the hand-maintained documents plus the one drift note. The commit carries the Generated-by trailer.

Checklist

• One subsystem group only (Desktop and frontend, 7 documents)
• Refs #3522 in the commit message
• Paired translations move together (CSS governance pair, translation_status: synced)
• last_verified set to the audit date (2026-09-04)
• Historical review content kept as written; only the metadata and drift note added

[hqhq1025]

I found one P2 documentation-contract issue.

The diff adds standard metadata to six Desktop/frontend documents and a drift banner to the review pinned at 0ad579d33; it does not change implementation or the generated 249-file surface inventory. I checked every changed file, the current Settings kit and workbar paths, the Astryx patch path, the English/Chinese CSS-governance pair, the generated inventory, and the clean merge tree against current main (5846521372d2dd0d3d2d33dc7784dd046dc3f7c8).

Validation passed: hosted exact-head test run 33930543481, Astryx inventory coverage (249 files), its 19 tests, renderer architecture (98 tests), ASF headers, repository format check, and git diff --check. I did not rerun interactive Desktop/Storybook visual acceptance; this patch changes documentation only.

Automated review notice: This comment was posted by an automated review agent operated by hqhq1025. It is not an independent human review and does not replace one.

[hqhq1025]

[P2] Do not mark these historical audit snapshots as current

This file is still the August 9 branch audit and still states a 183-file inventory at lines 34-36, while the exact-head generator now reports 249 files. The same problem is more concrete in docs/settings-astryx-deep-review.zh-CN.md: the body remains the August 3 pre-refactor review (for example, lines 57-64 say the other 13 pages and every SettingsSection use cards), but current settings-section.tsx:37-45,97-128 implements the open row-group design and current memory/health pages already use MoreMenu and StatusDot. The newly added implementation_status: current, document_status: current, and last_verified: 2026-09-04 therefore turn historical findings into advertised current guidance. Please mark the dated review records as historical/archive (and use the same explicit pinned-record treatment consistently), or update their substantive claims to the current tree before calling them current.

[hqhq1025]

Re-reviewed exact head 729870a0cd7bc6dc4076eb8646c3bd02577fb99e after the merge from main.

The existing P2 remains, with one refreshed number. docs/astryx-full-surface-audit.md:1-9 marks the August 9 audit as current, but its body still says the audited inventory contained 183 files at lines 34-36; the exact-head generator now reports 247 files. docs/settings-astryx-deep-review.zh-CN.md:1-9 likewise marks the August 3 review current while lines 57-64 describe the pre-refactor card layout. The current SettingsSection implements open row groups at settings-section.tsx:37-45,97-128, and current settings pages use MoreMenu and StatusDot.

The merge commit did not change either historical document or settings-section.tsx relative to the previously reviewed commit. The prior inline thread remains current, although its generated-inventory count was 249 before this main merge; the current exact-head count is 247. I found no additional P0-P3 issue in the other Desktop/frontend documents.

Validation: hosted test passed on this exact head; Astryx surface inventory coverage passed at 247 files with one exclusion; its tests passed 19/19; renderer architecture passed 101/101; repository format, ASF headers, and git diff --check passed; and current main produced a clean synthetic merge tree identical to the reviewed tree. I did not rerun interactive Desktop or Storybook visual acceptance.

Automated review notice: This comment was posted by an automated review agent operated by hqhq1025. It is not an independent human review and does not replace one.

[hqhq1025]

Re-reviewed exact head 91cfb86239530c70bc042ec331c18daacf5d6d24.

One P2 documentation-lifecycle issue remains. The new status banners correctly explain that docs/astryx-full-surface-audit.md and docs/settings-astryx-deep-review.zh-CN.md are historical snapshots whose findings are retained as written, but their machine-readable frontmatter still says implementation_status: current, document_status: current, and last_verified: 2026-09-04. That contradicts both the new 2026-09-05 banners and the repository documentation standard, which defines Historical material as content retained to explain past choices. docs/frontend-architecture-astryx-review-2026-08-09.md has the same mismatch. These audit records should use historical lifecycle metadata (and a consistent verification date) rather than continuing to advertise themselves as current guidance.

The incremental commit otherwise accurately records the current 247-file inventory and the open-row SettingsSection/MoreMenu/StatusDot implementation. Hosted test, the 247-file inventory gate and its 19 tests, ASF headers, git diff --check, and a clean patch-preserving merge onto current main (12ebc45e6fe43b2eebd7dfe61f5c1fa92c0c873a) passed. I did not rerun interactive Desktop/Storybook visual acceptance or re-evaluate every subjective finding retained in the historical reports.

Automated review notice: This comment was posted by an automated review agent operated by hqhq1025. It is not an independent human review and does not replace one.