Project Finalization — Quality, Documentation, and Cleanup

[phtcosta]

Problem Statement

The rv-android project is functionally complete with ~10 days remaining before thesis submission deadline (2026-04-13). The system works well but needs finalization: archive deprecated modules, remove dead code, enforce code quality (lint + format), generate comprehensive documentation for all modules, increase test coverage in under-tested modules, close obsolete issues/changes, and verify everything works end-to-end.

Affected Domains

• Core (rv-android-core)
• Platform (rv-platform)
• Experiment (rv-experiment)
• Agent (rv-agent)
• Instrumentation (rv-monitor-generator, rv-instrumentation)
• Analysis (rv-static-analysis, rv-coverage, rv-screen-parser)
• Tools (rv-tools, rv-uiautomator, rvagent-tool, aperv-tool, aperv-llm-validation)

Related FRs/NFRs

• NFR1 (Maintainability), NFR6 (Documentation), NFR8 (Reproducibility)

Current State Diagnosis

Aspect	State
Modules	16 in workspace, 2 archive candidates (rvsmart-tool, rv-agent-validation)
Tests	3,713 total. Gaps: rv-uiautomator (3), rv-instrumentation (12), rv-monitor-generator (17)
Docs missing	8 modules without architecture.md, 3 without CLAUDE.md, 2 without README
Code quality	Formatting debt across all modules
Open issues	11 open, several obsolete (rvsmart #34/#35/#36/#39)
OpenSpec changes	5 active changes that need archival (gh34/35/36-rvsmart, gh43-aperv-llm, gh9-docker)
OpenSpec specs	rvsmart spec must be archived; rvsmart refs in aperv/platform/tools specs must be removed

Task Groups

TG1: Housekeeping & Module Archival

• Archive rvsmart-tool and rv-agent-validation to backup/
• Archive openspec/specs/rvsmart/ to backup/openspec-specs-rvsmart
• Update pyproject.toml workspace members
• Update rv-platform __init__.py (remove rvsmart lazy import)
• Update aperv-tool references to rvsmart
• Remove rvsmart refs from specs: tools, aperv, platform
• Remove rv-agent-validation refs from specs: agent, analysis
• Close obsolete issues (feat(rvsmart): redesign exploration algorithm — dual hash, structural navigation, 3-phase exploration #34, rvsmart: fix exploration bugs and improve static analysis usage #35, rvsmart: fix exploration efficiency — 93.9% iteration waste on revisited states #36, rvsmart: Track B targeted improvements — retry budget, sterile blacklist, forward navigation, dual hash #39)
• Archive stale OpenSpec changes (gh34, gh35, gh36, gh43, gh9)

TG2: Dead Code Removal

• /rv-cleanup on each of the 14 remaining modules
• Priority: rv-android-core (77% dead constants), rv-agent (unused imports)
• Remove stale TODO/FIXME comments (10 total)

TG3: Code Quality — Lint & Fix

• /rv-qa-lint-fix on each of the 14 remaining modules
• black formatting, isort imports, flake8 fixes
• Per-module to avoid massive diffs

TG4: Code Documentation — Docstrings

• /rv-doc-code on key files per module
• Priority: public APIs, entry points, complex classes

TG5: Module Documentation — CLAUDE.md, README, Architecture

• /rv-doc-generate-claude-md for rvagent-tool, aperv-tool, aperv-llm-validation (missing)
• /rv-doc-architecture for 8 modules missing arch docs + aperv-llm-validation
• /rv-doc-readme for aperv-tool, aperv-llm-validation (missing)
• Update existing docs for all modules (/rv-docs-sync)

TG6: Test Coverage

• /rv-test-add for under-tested modules
• Priority: rv-uiautomator (3 tests!), rv-instrumentation (12), rv-monitor-generator (17)
• Secondary: rv-tools (81 for 60 src files)

TG7: Final Verification & Review

• /rv-verify on ALL 14 modules
• /rv-code-reviewer on key modules (core, agent, platform, experiment)
• Close/assess remaining open GitHub issues
• pyproject.toml metadata audit (versions, descriptions, authors)
• Verify CLI entry points (rv-experiment, rv-platform, rv-agent)
• Generate project metrics summary (LOC, tests, complexity per module)
• Final OpenSpec specs sync

Acceptance Criteria

• TG1: rvsmart-tool and rv-agent-validation archived; rvsmart spec archived; workspace builds cleanly; obsolete issues closed
• TG2: No dead imports; dead constants removed; no stale TODO/FIXME
• TG3: black/isort/flake8 clean on all modules; all tests still pass
• TG4: Key files in all modules have docstrings
• TG5: All 14 modules have CLAUDE.md, README.md, and architecture.md
• TG6: rv-uiautomator >=20 tests; rv-instrumentation >=25; rv-monitor-generator >=25
• TG7: rv-verify passes on all modules; CLI entry points functional; metrics report generated
• TG7: pyproject.toml metadata consistent across all modules
• TG7: Project metrics report generated

Priority

High — thesis deadline 2026-04-13

Track

Quick Path — OpenSpec change: gh48-project-finalization