acdream/docs/reviews/architecture-documentation-assessment.md

Architecture and documentation assessment

Status: complete at the recorded baseline.

Declared authority order

The repository declares milestones authoritative for the active outcome, the roadmap authoritative for ordering, issues authoritative per defect, and architecture documents authoritative for implementation shape. Research and dated plans are historical evidence. This is a reasonable model, but the current documents duplicate enough mutable state that the order does not resolve contradictions reliably.

Initial architecture-to-repository observations

Subject	Documented current contract	Repository evidence	Initial assessment
Graphics backend	Vulkan only; OpenGL deleted	App references Silk.NET.Vulkan; Vulkan/RHI source exists	architecture matches code; public README is stale
Gameplay UI	one retained stack; ImGui deleted	no AcDream.UI.ImGui project; retained UI in App	architecture matches code; README and some rule wording are stale
Runtime boundary	Runtime may depend on Core, Core.Net, Content, Platform, Plugin.Abstractions; never App/UI/backend	project/source graph matches; dependency guards pass	confirmed
Headless boundary	Headless directly references Runtime only	project graph and executed loaded-assembly guards match	confirmed; operability exceptions recorded separately
Platform boundary	Platform has zero references	project graph and complete two-file source review match	confirmed
Reference workflow	six vendored reference projects	only uninitialized WorldBuilder gitlink exists	documented process is not reproducible
GameWindow shell	architecture checkpoint says 1,622 lines	current file is 1,860 lines	still primarily a composition/callback shell, but checkpoint and navigability claim have drifted
UI abstraction	backend-neutral panel/input seam	directly references Runtime and Silk input; old panel renderer has no implementation	boundary name and owned concerns no longer match
Presentation stacks	one retained retail UI	retained retail UI ships, but unreachable IPanelRenderer/ImGui-era panels remain compiled and tested	dead second design obscures the shipping stack
Build authority	.NET 10 solution with warnings-as-errors	no pinned SDK/locked restore/central build settings; policy copied inconsistently across 44 projects	a commit is not a reproducible toolchain definition
Issue authority	one authoritative status per defect	380 headings/378 IDs, about two-thirds closed history, 29 broken links	tactical queue is also an archive and research journal

Documentation-system concerns under review

1. README.md currently contradicts the architecture on the most basic user prerequisite: Vulkan versus OpenGL and the existence of ImGui.
2. docs/README.md is presented as a current-state guard but predates completed work linked from the same page.
3. AGENTS.md is 1,615 lines and embeds a long commit-by-commit status ledger, rollback commands, local credentials, machine paths, tool instructions, architectural rules, and reference tutorials. Its normative rules are hard to distinguish from stale operational history.
4. The architecture document similarly combines stable dependency rules with current phase state, historical campaign checkpoints, test totals, exact commits, and future target designs.
5. Required links into claude-memory/ and .claude/skills/ are absent from the baseline worktree.
6. The current milestone, roadmap, and world-interaction plan each preserve a different pre-closeout state even though the plan itself has a later closeout section. Authority precedence cannot resolve a contradiction inside every claimed authority.
7. The mandatory WorldBuilder inventory still gives OpenGL and ImGui design direction after both were deleted.
8. The issue ledger's status convention is not mechanically enforceable: two duplicate IDs, nine missing/nonstandard status blocks, and broken links sit inside a 19,073-line file every session is instructed to scan.
9. The active-document link check found three broken links even before the historical corpus: the missing claude-memory/MEMORY.md map and two missing Phase O documents linked from roadmap line 505.
10. The retail-divergence authority has correct headline row counts but is not maintainable as a review surface: 809 KB in 525 physical lines, 243 lines longer than 1,000 characters, a 45,240-character heading, and 11 unique unresolved source/test paths among 843 path citations. Its title is six weeks behind its own latest entries.
11. The approved plugin architecture reads as an implemented contract but is mostly aspirational. The manifest accepts every positive API version, declared dependencies are unused, the promised abstractions package has no pack/version metadata, and callback-fault/hot-reload behavior differs from the design.
12. The launcher consumes a production GitHub Release manifest, but the repository contains no production release workflow or manifest generator, no tags/central product version, and no contribution, security, changelog, or code-ownership documents.
13. AGENTS.md explicitly claims to be synchronized from CLAUDE.md, but the files differ by 255 insertions and 27 deletions. The stale copy restarts a completed interaction slice and disagrees about reference count, retired AC2D status, and streaming-radius configuration. This makes the executing assistant, rather than the repository commit, select project truth.
14. Tracked memory/ documents labeled “current truth” still prescribe ImGui frame submission, the deleted UI.ImGui project, OpenGL bindless capability gates, and resuming the now-complete interaction Slice 4. Because root instructions route work into these files, they are active contradictions, not harmless archived notes.
15. A repository-wide scan of all 1,014 tracked Markdown files found 397 broken relative-link occurrences, representing 357 distinct file/target pairs. Historical records account for most of the debt: 197 pairs in docs/research and 130 in docs/superpowers. The current authority layer has a much smaller but material set: docs/README.md points at the absent claude-memory/MEMORY.md; the roadmap points at two absent Phase O records; one old handoff points at a deleted VFX test; and one tracked memory index points at a missing phase audit. docs/ISSUES.md contributes 25 distinct broken Markdown-link pairs. Historical link rot should be repaired or frozen by support tier, but it is not equivalent in severity to a broken current-authority link.
16. The dated plans/specs/research system is now 80 top-level plans, 100 superpowers/plans, 96 specs, and 700 research Markdown files. Recent campaign plans do generally put status near the top, which is good, but several preserve contradictory status prose in-place (for example an IN FLIGHT label followed immediately by a later CAMPAIGN CLOSED clause). There is no generated active/archive index or schema validation; readers must interpret narrative amendments to decide which paragraph is operative.

Source-structure census

The project-reference graph is acyclic and the primary declared assembly boundaries are present: Platform has no references, Headless references Runtime only, and Runtime has no App/UI/backend reference. The maintainability risk is inside several of those correct graph boxes. Source hotspots are highly concentrated: App has 37 files above 1,000 lines, Runtime 20, Core 13, and the five largest owned files range from 3,754 to 6,345 lines. Campaign/history language also remains densest in those owners (2,349 rough source occurrences in App, 698 in Core, and 491 in Runtime).

Assembly	Primary assessment at this checkpoint
AcDream.App	Layer role is valid, but composition/render/UI/network sidecars remain too concentrated; dead presentation/backend seams, source-shape tests, static diagnostics, and the unconditional smoke-plugin publish make the shipping boundary hard to reason about.
AcDream.Runtime	Project boundary is real and well guarded, but RuntimeSetPositionState (6,283 lines) and several 2,500–3,200-line gameplay/entity owners combine algorithms, state machines, ledgers, and diagnostics beyond a human-scale change unit.
AcDream.Core	Contains valuable faithful ports with strong oracle citations, but giant physics units, process-static diagnostics, external-type leakage, and campaign/issue narrative obscure the stable algorithms.
AcDream.Core.Net	Protocol/session ownership is coherent; WorldSession remains a 3,754-line transport/lifecycle owner with dense historical comments, direct environment probes, and synchronous shutdown risk that warrants focused refactoring only after behavior is pinned.
AcDream.Content	Prepared-content boundary is conceptually clean, but public mesh DTOs still expose Chorizite types and GL-ABI vocabulary despite a Vulkan-only consumer.
AcDream.Headless	Presentation dependency guard is strong. Silent plugin callback failure and process-static/config conventions weaken operability; three files exceed 1,000 lines.
AcDream.Launcher.Core / Launcher	Update/install security and transaction design are unusually thorough, but the full-suite lock inversion is a release blocker and there is no owned production release publisher. Several view-model/orchestrator/update owners are oversized.
AcDream.Platform	Small, cohesive, and dependency-free as documented.
AcDream.Plugin.Abstractions	BCL-only and small, but not yet a versioned/published compatibility contract; the approved design substantially overstates the implemented surface.
AcDream.UI.Abstractions	Input/keybinding pieces remain useful; the project also retains a dead ImGui-era panel stack and directly depends on Runtime/Core, so its name no longer describes one neutral abstraction layer.
Bake / CLI / tools	Bake's transaction boundary is understandable though its runner is 1,067 lines. CLI and most forensic tools are campaign utilities without a support tier; many are excluded from the solution or require developer-local paths.

Recommended documentation information architecture

1. Keep README.md public and release-oriented: supported platforms/backend, install/run path, actual maturity, credential-storage disclosure, licence, and links to release/security/contribution documents. Do not duplicate campaign state or rolling test totals there.
2. Make docs/README.md a stable navigation page plus a generated, dated status block sourced from one structured milestone ledger. A CI check should fail when the block, project graph, backend, links, or reported gate command disagrees with the repository.
3. Restrict architecture documents to durable component ownership, dependency rules, threading/lifetime contracts, data flow, and intentional seams. Move commits, rollback recipes, test counts, and campaign closeout narrative into dated decision/closeout records.
4. Replace duplicated AGENTS.md/CLAUDE.md bodies with one tool-neutral maintained instruction source and generated thin adapters. Agent-only tool syntax should not carry product truth.
5. Normalize issues and retail divergences into one record per stable ID with machine-readable status, owner, current rationale, oracle, live symbol/path, and review date. Generate compact active indexes; archive amendment history separately.
6. Treat plans, specs, research, probes, raw captures, and memory as explicit support tiers: active, superseded, immutable evidence, or external artifact. Validate relative links only against the promises of each tier and prevent a historical document from calling itself “current truth.”
7. Add one owned release runbook and automation for pinned clean restore/build, the complete bounded test matrix, installed-DAT/live/manual lanes, per-RID packages, manifest/checksum/SBOM/provenance generation, rollback, and public publication.

Positive architecture findings

• The project-reference graph is acyclic and the most important assembly boundaries are real: Platform is dependency-free, Headless references Runtime only, Runtime does not reference App/UI/backend assemblies, and Plugin.Abstractions is BCL-only.
• GameRuntime ownership, generation gating, teardown ledgers, updater transaction design, path traversal/hash validation, and credential redaction have unusually substantial adversarial test coverage.
• The named-retail oracle is committed and searchable, so the core retail- fidelity workflow does not depend entirely on the missing external reference checkouts. The weakness is provenance/licensing and surrounding reference reproducibility, not absence of the primary algorithm corpus.
• Production code builds without warnings at the baseline; all 26 rebuild warnings are confined to test projects. Current package-source vulnerability lookup reported no known vulnerable direct or transitive packages, although the unpinned restore prevents treating that as a permanent commit property.