[TASK]: Chore: Streamline documentation workflow and automate architecture updates

[aj1126]

Title

Chore: Streamline documentation workflow and automate architecture updates

---

Description

Problem Statement

As the project scales, manual documentation curation is introducing unnecessary friction during branch synchronization and releases.

• Standalone sprint files (SPRINT_01.md, etc.) clog the active /docs root directory.
• The architecture.md file requires manual text edits whenever modules change, increasing the risk of documentation drift.
• There is no local safety net ensuring documentation is generated and validated before changes are committed.

Proposed Solution

Transition from a manual curation model to an automated, Code-as-Source documentation ecosystem using automated scripts and local Git lifecycle hooks.

---

Action Items

1. Purge & Archive Historical Artifacts

• Create a dedicated archive directory: docs/archive/sprints/.
• Move all past sprint documentation (SPRINT_*.md) into the archive folder to clean up the primary workspace root.
• Deprecate standalone Markdown files for future sprint logs; transition sprint tracking entirely to GitHub Issues/Projects.

2. Automate architecture.md Syncing

• Enforce Transclusion: Remove hardcoded, copy-pasted layout diagrams from architecture.md and link natively to the single source of truth files (docs/diagrams/architectureDiagram.mermaid and docs/diagrams/sequenceDiagram.mermaid).
• Code-Driven Layout Maps: Refactor scripts/generate-docs.js to dynamically parse structural directories (src/analytics/, src/ingestion/, src/delivery/). Have it extract module descriptions from standard header comment blocks (e.g., predictive.js, worker.js) and auto-generate the "Current Implementation" module grid inside architecture.md.

3. Protect the Main Branch with Pre-Commit Hooks

• Install and configure husky to manage local Git hooks.
• Establish a .husky/pre-commit hook running the following pipeline sequence on every local commit:

1. npm run docs:generate (rebuilds directory maps and layouts)
2. git add docs/ (automatically stages the fresh documentation changes)
3. npm run docs:check (runs validation suite via scripts/validate-docs.js)

• Ensure the commit safely aborts if docs:check flags missing nodes or structural anomalies.

---

Definition of Done

• Active /docs directory is pruned of historical sprint notes.
• Running npm run docs:generate parses the src/ directory tree and populates architecture.md dynamically.
• Committing code changes locally triggers the automatic documentation build and test suite, failing the commit if updates are mismatched.