203 lines
10 KiB
Markdown
203 lines
10 KiB
Markdown
# 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`](coverage-ledger.md) records the inspected scope and
|
|
completion evidence.
|
|
- [`findings-ledger.md`](findings-ledger.md) is the deduplicated evidence-backed
|
|
finding register.
|
|
- [`architecture-documentation-assessment.md`](architecture-documentation-assessment.md)
|
|
compares the documented ownership model with the repository and evaluates
|
|
the documentation hierarchy.
|
|
- [`comment-reference-inventory.md`](comment-reference-inventory.md) classifies
|
|
comments and historical/external references by maintainability value.
|
|
- [`test-quality-audit.md`](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`](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.
|