docs: documentation architecture audit + full Phase 0/2/3 update (commit 4ba633a)

[SevWren]

Problem Statement

After commit 4ba633a added 180+ Pester tests, Invoke-Build automation, and a GitHub Actions CI/CD pipeline, the project's documentation remained frozen in a pre-test-infrastructure state. Developers and future agents reading any of the 60+ documentation files encountered:

• Wrong build commands (build.ps1 referenced instead of .build.ps1 / Invoke-Build)
• Incomplete repository structure diagrams missing the entire Tests/ tree and CI config files
• No contributor testing workflow -- CONTRIBUTING.md had no mention of Pester, TDD, or quality gates
• Invisible test infrastructure -- 180+ tests existed but none of the core docs (README, CLAUDE.MD, ARCHITECTURE) mentioned them
• Session artifacts cluttering the repo -- handoff docs, audit reports, and one-time analysis files sat as peers to living documentation
• No regression traceability -- bugs documented in FORENSIC_REVIEW.md had no link to which Pester tests now protect against their recurrence

Solution

A 5-agent parallel documentation audit identified 25 files requiring updates, categorized by priority. Changes were applied in 4 phases:

• Phase 0: Applied improve-codebase-architecture deletion test to 11 session work products (audit reports, handoff docs, completion reports). Archived them to docs/reports/ as dated historical records. Created docs/reports/README.md index.
• Phase 1 (previous session): Updated 6 critical developer-facing files (README, CLAUDE.MD, CONTRIBUTING, TEST_PLAN, CHANGELOG, src/README).
• Phase 2: Updated 9 high-priority spec and process files (ARCHITECTURE, INSTALL, PRD, TRACEABILITY_MATRIX, DISTRIBUTION_STRATEGY, SPRINT_PLAN, ROADMAP, NOTIFICATION_ENGINE_SPEC, CONFIGURATION_SPEC).
• Phase 3: Updated 8 medium/low priority files (docs/README, NPR, RISK_REGISTER, GLOSSARY, FEATURE_MATRIX, DOC_IMPACT_ANALYSIS, NEXT_STEPS, FORENSIC_REVIEW).

User Stories

1. As a new developer, I want README.md to show the complete repository structure, so that I can immediately find the test infrastructure without exploring manually.
2. As a developer, I want CONTRIBUTING.md to document the TDD workflow, so that I know I must write tests before submitting a PR.
3. As a developer, I want INSTALL.md to use the correct build commands, so that running the documented commands actually works.
4. As an agent resuming work on this codebase, I want CLAUDE.MD to accurately reflect the repository layout, so that I don't waste time searching for files that don't exist where the docs say they do.
5. As a developer, I want TEST_PLAN.md to distinguish automated from manual tests, so that I know which test cases are already covered by CI.
6. As a project stakeholder, I want CHANGELOG.md to document the test infrastructure addition, so that the project history accurately reflects all significant work.
7. As a developer reading ARCHITECTURE.md, I want a Quality Assurance section, so that I understand the test coverage posture at a glance.
8. As a developer reading NOTIFICATION_ENGINE_SPEC.md, I want a prominent warning about zero test coverage, so that I treat changes to DailyMotivation.ps1 with appropriate manual testing discipline.
9. As a developer reading PRD.md, I want a Requirements Validation Matrix, so that I know which functional requirements have automated validation.
10. As a future maintainer, I want FORENSIC_REVIEW.md to map each historical bug to its Pester regression test, so that I can verify protection is still in place.
11. As a new contributor, I want GLOSSARY.md to define Pester, PSScriptAnalyzer, and Invoke-Build, so that I understand terminology used throughout the docs without external research.
12. As a developer, I want NPR.md to formally document the 80% coverage requirement, so that it is a first-class non-product requirement rather than an informal convention.
13. As a developer, I want the repository root to contain only living documents, so that session artifacts and one-time reports do not obscure the project structure.
14. As a developer reading TRACEABILITY_MATRIX.md, I want module-level test coverage listed, so that I can trace requirements through to specific test files.
15. As a release manager, I want DISTRIBUTION_STRATEGY.md to use the correct build system commands, so that release builds are reproducible.
16. As a project stakeholder, I want SPRINT_PLAN.md to record Sprint 0 infrastructure work, so that the project history shows when and how the engineering foundation was established.
17. As a developer reading ROADMAP.md, I want to see the completed engineering foundation milestone, so that I understand the project's quality posture.
18. As a risk manager, I want RISK_REGISTER.md to include test infrastructure risks (dependency drift, coverage regression, notification engine changes), so that these risks are tracked and mitigated.

Implementation Decisions

• docs/reports/ as an archive module: Session work products follow a dated-filename convention (FILENAME-YYYY-MM-DD.md) and are never updated in place. New sessions create new dated files. This gives the archive a stable interface (append-only) behind a simple module boundary (the directory).
• Deletion test for archival decisions: A file earns its place at the repo root or in docs/ if deleting it would cause its complexity to reappear elsewhere (callers would need to reconstruct its content). Handoff docs, audit reports, and completion reports all fail this test.
• TESTING.md stays at repo root: Unlike archived files, TESTING.md is a living developer guide that is actively referenced by CONTRIBUTING.md, INSTALL.md, and CLAUDE.MD. It passes the deletion test.
• No changes to source code: All changes are documentation-only. No .ps1, .psm1, or test files were modified in this work.
• Cross-reference integrity: All internal links to moved files were updated in the same commit as the moves.

Testing Decisions

This PRD covers documentation changes only. There is no source code to test. Validation is performed by:

1. Checking that all cross-references to moved files resolve correctly: grep -r "MODERN-POWERSHELL-SCAFFOLDING\|INITIALIZATION-BUGS\.md" . --include="*.md" | grep -v "docs/reports"
2. Verifying all 25 targeted files contain their expected new sections
3. Confirming git log --oneline -6 shows the correct 4-commit sequence

Out of Scope

• Changes to any source code (.ps1, .psm1, test files, build scripts)
• Adding new features or fixing bugs
• Addressing the Notification Engine 0% coverage gap (tracked as a separate backlog item in NEXT_STEPS.md)
• Updating issues BUG: $PSScriptRoot resolution fails in PS2EXE compiled executable #3, BUG: DailyMotivation.ps1 doesn't call Initialize-AppData, assumes MainApp already ran #5, BUG: Silent exit behavior masks real initialization problems #6, BUG: %TEMP% fallback in ConfigManager not used consistently across scripts #7 (tracked in GitHub issues)

Further Notes

Commits implementing this work (all on main):

• 8d6cb0d -- Phase 1: Critical doc updates (6 files)
• 36a495e -- Implementation plan published
• b311430 -- Phase 0: Archive session work products to docs/reports/
• 037477d -- Phase 2: High-priority updates (9 files)
• 31148f3 -- Phase 3: Medium/low priority updates (8 files)

Full audit report: docs/reports/AUDIT-MASTER-REPORT-COMMIT-4ba633a.md

Most important finding: DailyMotivation.ps1 (Notification Engine) has zero automated test coverage. This is the highest quality risk in the codebase. See docs/NOTIFICATION_ENGINE_SPEC.md -- Test Coverage Warning section for the testing approach roadmap.