1 changed files with 48 additions and 0 deletions
@@ -47066,6 +47066,54 @@ This section defines the ordered milestone plan for CleverAgents v3.x, mapping a

 ---

+### v3.9.0 — Documentation & Feature Updates
+
+**Goal**: Deliver comprehensive documentation improvements, targeted feature additions, quality enhancements, and developer-experience upgrades that do not fit within the scope of the major feature milestones (v3.2.0–v3.8.0). This milestone ensures the platform is well-documented, thoroughly tested, and ergonomic for both end-users and contributors before the next major capability cycle.
+
+**Spec Coverage**: §Documentation, §Quality Gates, §Cross-Cutting Concerns, §CLI Commands, §Module Definitions
+
+**Key ADRs**: No new ADRs required for this milestone. All changes are clarifications, documentation additions, or minor feature improvements that fall within existing architectural decisions.
+
+#### Deliverables
+
+| # | Deliverable | Spec Reference | Verifiable Check |
+|---|-------------|----------------|-----------------|
+| 1 | Comprehensive API reference documentation for all public modules | §Documentation — API Reference | `nox -s docs` passes; all public symbols have docstrings; MkDocs API reference renders without errors |
+| 2 | User guide: Getting Started walkthrough (install → first plan) | §Documentation — User Guides | `docs/user-guide/getting-started.md` exists and covers install, init, resource add, action create, plan use/execute/apply |
+| 3 | User guide: Actions and Plans deep-dive | §Documentation — User Guides | `docs/user-guide/actions-and-plans.md` exists; covers Action YAML schema, plan lifecycle, corrections, subplans |
+| 4 | User guide: Resources and Projects | §Documentation — User Guides | `docs/user-guide/resources-and-projects.md` exists; covers resource types, DAG, project linking, context policies |
+| 5 | Architecture documentation updated to reflect v3.6.0–v3.7.0 additions (LSP, devcontainer, TUI) | §Module Definitions | `docs/architecture.md` updated; LSP Registry, Devcontainer, TUI Materializer sections present |
+| 6 | CONTRIBUTING.md updated with current nox session list, commit conventions, and PR workflow | §Cross-Cutting Concerns — Developer Experience | `CONTRIBUTING.md` reflects current `nox -l` output; commit message format documented |
+| 7 | Improved error messages: all `ValueError`/`RuntimeError` raises include actionable guidance | §Cross-Cutting Concerns — Error Handling | Manual review of all `raise` statements; each includes a hint or remediation step |
+| 8 | CLI `--help` text reviewed and updated for all commands | §CLI Commands | `agents --help` and all subcommand `--help` outputs are accurate and complete |
+| 9 | Test coverage ≥ 97% maintained; new coverage for previously untested edge cases | §Quality Gates | `nox -s coverage_report` passes with ≥ 97% line coverage |
+| 10 | Performance: no ASV benchmark regressions introduced by documentation or minor feature changes | §Quality Gates | `nox -s benchmarks` passes; no regression > 10% vs. v3.7.0 baseline |
+| 11 | Technical debt: resolve all `TODO`/`FIXME` comments tagged for v3.9.0 | §Cross-Cutting Concerns — Technical Debt | `rg "TODO.*v3\.9|FIXME.*v3\.9"` returns no results |
+| 12 | Developer tooling: `nox -s dev_setup` script for one-command contributor onboarding | §Cross-Cutting Concerns — Developer Experience | Running `nox -s dev_setup` on a clean checkout installs all dependencies and runs `nox -s lint typecheck unit_tests` successfully |
+| 13 | Showcase examples: at least 3 end-to-end workflow examples in `examples/` | §Workflow Examples | `examples/` contains ≥ 3 subdirectories each with a `README.md`, action YAML, and actor YAML |
+| 14 | FAQ document covering top 10 common user questions | §Documentation — FAQ | `docs/faq.md` contains ≥ 10 Q&A entries covering install, configuration, plan lifecycle, and troubleshooting |
+| 15 | Changelog updated with all changes from v3.2.0 through v3.9.0 | §Documentation — Changelog | `CHANGELOG.md` has entries for each milestone; follows Keep a Changelog format |
+
+#### Key Architectural Constraints
+
+- **No breaking changes**: v3.9.0 must not introduce breaking changes to the public API, CLI interface, or A2A protocol extensions. All changes are additive or corrective.
+- **Spec-first**: Any minor feature addition discovered during documentation work must be spec-covered before implementation proceeds, per the spec-first invariant.
+- **Documentation co-located with code**: API reference documentation is generated from docstrings; user guides live in `docs/`; no documentation is duplicated across locations.
+- **Error message format**: All user-facing error messages follow the pattern `<what went wrong>. <why it happened>. <how to fix it>.` — three sentences, actionable.
+- **Nox session parity**: All quality gates remain executable via `nox`; no ad-hoc scripts introduced outside the `noxfile.py`.
+- **Coverage floor**: The 97% line coverage floor established in v3.2.0 must not regress. New code must be covered before merge.
+
+#### Definition of Done
+
+- All 15 deliverables verified (documentation reviewed by at least one human reviewer; automated checks pass)
+- `nox` passes with coverage ≥ 97%
+- No open P0/P1 bugs in v3.9.0 milestone
+- All 21 open milestone issues resolved or explicitly deferred to a future milestone with documented rationale
+- Documentation site builds and deploys without errors (`nox -s docs`)
+- CONTRIBUTING.md accurately reflects the current development workflow
+
+---
+
 ### Cross-Milestone Quality Gates

 These quality gates apply to **every milestone** and must pass before a milestone is considered complete: