acdream/docs/reviews/2026-08-17-release-maintainability-audit.md

acdream release maintainability audit

Status: complete — public-release no-go
Audit baseline: commit 15539a22a67f8d915d88f8b1d8126cd55eedda6e
Baseline tree: 4de2634ee7f528fe149fc0817247988f8b6bf67f
Started: 2026-08-17 Completed: 2026-08-18

Objective

Determine whether a human development team can safely maintain and release acdream without relying on undocumented AI conversations, campaign history, or machine-local context. This is a review-only audit. It does not modify owned source, tests, configuration, or existing documentation.

Deliverables

• coverage-ledger.md records the inspected scope and completion evidence.
• findings-ledger.md is the deduplicated evidence-backed finding register.
• architecture-documentation-assessment.md compares the documented ownership model with the repository and evaluates the documentation hierarchy.
• comment-reference-inventory.md classifies comments and historical/external references by maintainability value.
• test-quality-audit.md records the complete test-source review and every test-quality exception worth acting on.

Review boundaries

Deep review covers all source-controlled code under src/ and tools/, all source-controlled test code under tests/, the public entry points, active architecture and planning authorities, and their links into research/history. Generated binaries, build output, retail data, and external repositories are not judged as owned code. Their discoverability, licensing, reproducibility, and use as required evidence are in scope.

Evidence and classification rules

Each finding records an exact path/line or a reproducible repository command, impact, confidence, and recommended direction. Severity means:

• P0 — release blocker: responsible public release should not proceed.
• P1 — high: likely to mislead maintainers or make important changes unsafe.
• P2 — medium: material recurring maintenance cost or localized false confidence.
• P3 — low: cleanup that improves clarity but does not materially impair work.

Tests are not called “useless” merely because they are small or repetitive. That label is reserved for a test that cannot detect a meaningful regression. Other low-signal tests are classified as misleading, redundant, tautological, implementation-coupled, obsolete, weakly asserted, or misplaced.

Executive conclusion

acdream is not architecturally hopeless or uniformly “AI spaghetti.” Its assembly graph has meaningful boundaries, the Runtime/App split is real, and several difficult lifetime, updater, transport, and retail-fidelity mechanisms have strong tests. A human team could maintain it after a focused stabilization program.

It is not ready for a responsible public release at this baseline. The audit records 34 findings: four P0, 25 P1, and five P2. The four blockers are:

1. no project licence and unresolved redistribution/provenance for committed reverse-engineering artifacts (F-001);
2. public setup documentation advertising the deleted OpenGL/ImGui stack instead of the shipping Vulkan client (F-002);
3. a reproducible launcher supervisor/process-exit lock inversion that hangs the official complete test process and can affect production disposal (F-009); and
4. CI does not execute the complete solution gate and omits Core plus most App tests (F-014).

The dominant maintainability risk is not one bad algorithm. It is the absence of a trustworthy release truth: current state is duplicated across enormous campaign journals, comments depend on missing/private context, tools and SDK resolution are machine-specific, and headline test counts include hundreds of contracts that did not execute.

What is already solid

• Production Release compilation succeeds with no production-code warnings.
• The project-reference graph is acyclic; Platform, Headless, Runtime, and Plugin.Abstractions satisfy their most important declared dependency rules.
• Per-project execution produced 14,747 passes and 77 reported skips. That is a substantial safety net even after discounting the misleading cases.
• Updater extraction, hashing, transaction/rollback, path safety, launcher credential redaction, generation gating, and teardown ownership receive unusually strong adversarial coverage.
• The primary named-retail algorithm corpus is committed and searchable.
• A current NuGet vulnerability lookup reported no known vulnerable direct or transitive packages, and the repository-wide common token/private-key scan found no matching secret prefix. These are point-in-time positives, not substitutes for pinned restore or artifact review.

Test verdict

The test corpus is valuable but its headline number is not a reliable release claim today. The review found:

• three entire cases with no meaningful runtime contract (the literal smoke tautology, the compile-only camera-interface test, and the empty skipped PVS scaffold), plus useless tautological assertions inside otherwise useful tests;
• 51 output-only diagnostic methods in the default suite;
• 271 asset/environment-gated facts that report success without exercising their named contract;
• at least 52 tests for an unreachable deleted presentation stack;
• 30 App source-reading files containing 560 literal-fragment assertions and 86 ordering-helper calls, including an explicitly temporary architecture freeze;
• one duplicate theory row silently removed during discovery, 26 clean-rebuild warnings, seven open load-sensitive tests, and real-time sleeps in timing contracts; and
• a precise table of contract-like test names whose assertions do not establish the behavior in their name.

The exact method/file catalog and classification is in test-quality-audit.md. Diagnostics are not called useless merely because they print useful evidence; they are classified as misplaced unless they also have a stable oracle.

Recommended stabilization order

1. Establish legal and release authority

Resolve project and research-artifact licensing/provenance; decide which decompiler/Ghidra/capture artifacts may be distributed; add the public licence, NOTICE coverage, security policy, contribution policy, changelog/version authority, credential-storage disclosure, and release runbook.

2. Make one bounded gate truthful

Fix the launcher deadlock with a deterministic regression test. Pin the .NET SDK and restore graph, make a clean warning-free build the gate, and run the complete solution in CI with per-project/process timeouts and hang artifacts. Turn unavailable DAT/live/environment prerequisites into explicit lanes and reported skips/failures; remove output-only apparatus from the release count; own the seven flakes rather than retrying them generically.

3. Repair current documentation before historical cleanup

Correct the Vulkan/UI/readiness README, generate current status from one ledger, synchronize or generate the agent instruction wrappers, retire stale “current truth” memory, and separate durable architecture from campaign history. Then validate active links and normalize the issue/divergence indexes.

4. Remove abandoned and ambiguous shipping surfaces

Delete or explicitly support the dead panel stack and stale OpenGL/probe apparatus; stop embedding the smoke plugin in release output; enforce plugin API/dependency/lifecycle contracts; centralize diagnostic configuration. Split giant owners only at proven ownership/lifetime seams, preserving retail algorithms and sabotage-verified behavior.

5. Make the repository reproducible for another human

Repair or archive the five broken tool projects, publish exact reference bootstrap revisions/licences, remove developer-home paths, and move opaque Ghidra projects/raw logs to an approved versioned artifact system. Keep compact fixtures, checksums, scripts, and evidence summaries in Git.

Scope limitations

This is a maintainability/release review, not a proof that all retail behavior is correct and not legal advice. Installed-DAT, live-server, visual, listening, physical-Linux, and manual generator gates were classified from their source and recorded evidence but not all re-executed. Package vulnerability results reflect the configured sources on 2026-08-18. The launcher hang was reproduced and captured; the seven other documented flakes all passed in the single per-project audit baseline and remain findings because their own issue records show recurrence.

The audit changed only the new records under docs/reviews/; it made no edits to owned source, tests, configuration, existing documentation, commits, or external systems.

Post-audit stabilization update — 2026-08-18

R1 has been implemented, fully gated, and preserved at 0a934cf5 on codex/release-stabilization. The launcher child is detached under the supervisor gate and stopped, unsubscribed, and disposed outside it; a deterministic captured-callback race test fails against the old mechanism and passes against the fix. Launcher.Core passes 339/339, and two fresh serialized complete Release runs each finish inside a 900-second hard bound with 14,748 passes / 77 skips / 0 failures.

This resolves F-009 technically but does not change the baseline audit's historical count; the checkpoint is committed but not yet merged to main.

The subsequent R2 gate checkpoint pins SDK feature band 10.0.300, adds a repository-owned bounded Release command and Windows CI workflow that discover and run all 12 test assemblies, captures TRX/log/environment/hash evidence, and collects mini dumps before an outer process-tree timeout. Its local evidence run reports 14,748 executed and passed / 77 skipped / 0 failed in 107.337 seconds. Three additional default-parallel solution runs pass without the previous Avalonia compositor cleanup failure after shown test windows were closed on their owning session.

This resolves F-014 technically on the campaign branch and partially addresses F-010/F-019. The public-release decision remains no-go because F-001, F-002, the 26 clean-build warnings, unpinned package graph, and the remaining high-priority release-governance/test-truth findings are untouched.