docs: update CHANGELOG.md and documentation for recent merged features #9310

Open
opened 2026-04-14 14:38:25 +00:00 by HAL9000 · 1 comment
Owner

Metadata

  • Commit Message: docs(changelog): update CHANGELOG.md and documentation for recent merged features
  • Branch: docs/update-changelog-recent-features

Background and Context

A documentation scan of the cleveragents/cleveragents-core repository was performed on 2026-04-14 by [AUTO-DOCS-1]. The scan identified the following documentation gaps:

  1. CHANGELOG.md coverage: The most recent CHANGELOG entry is docs(changelog): add plan action-arguments UNIQUE constraint fix (#4197) (commit acc5f0115563cc65674a9c08cddea0de28d489e7). Multiple recently merged PRs across milestones v3.2.0–v3.5.0 may not have corresponding CHANGELOG entries, including bug fixes, refactors, and feature additions merged in the last development cycle.

  2. docs/reference/ completeness: New CLI commands and modules introduced in recent milestones (A2A facade, event queue, guard enforcement, ACMS context policies) require reference documentation updates to reflect their current API surface.

  3. docs/development/ accuracy: Developer guides may not reflect the current test infrastructure (e.g., the coverage threshold change from 50% → 80% per issue #9264), updated nox session names, or new BDD feature file conventions.

  4. mkdocs.yml navigation: New documentation pages added for recent features may not be registered in the mkdocs navigation, causing them to be unreachable from the documentation site.

  5. README.md accuracy: The README may not reflect the current milestone status (v3.2.0–v3.5.0 active development) or updated installation/quickstart instructions.

The [AUTO-DOCS] supervisor (issue #9305) is performing its initial scan and has not yet dispatched workers to address these gaps. This issue tracks the concrete documentation work needed.

Expected Behavior

After completing this issue:

  • CHANGELOG.md has entries for all merged PRs since the last documented entry, following the Keep a Changelog format
  • docs/reference/ accurately documents all current CLI commands and public APIs
  • docs/development/ reflects current tooling, test infrastructure, and contribution workflows
  • mkdocs.yml navigation includes all documentation pages
  • README.md accurately describes the project's current state and milestone progress

Acceptance Criteria

  • CHANGELOG.md is audited against the git log since the last documented entry; missing entries are added under [Unreleased]
  • All recently merged PRs (last 20 closed PRs) are cross-checked against CHANGELOG entries
  • docs/reference/ CLI reference pages are updated for any new or changed commands
  • docs/development/ guides are reviewed and updated for accuracy (coverage thresholds, nox sessions, BDD conventions)
  • mkdocs.yml navigation is verified to include all pages under docs/
  • README.md milestone status section is updated to reflect current active milestones
  • All documentation changes pass mkdocs build without warnings
  • A PR is created from docs/update-changelog-recent-features targeting master

Subtasks

  • Audit CHANGELOG.md: Run git log --oneline since last CHANGELOG entry and identify merged PRs missing from CHANGELOG
  • Add missing CHANGELOG entries: For each undocumented merged PR, add an appropriate entry under [Unreleased] (Added/Changed/Fixed/Removed)
  • Review docs/reference/: Check CLI reference docs for agents session, agents plan, agents context policy, agents automation-profile, agents invariant commands
  • Update docs/development/: Verify coverage threshold documentation (50% → 80% per #9264), nox session names, and BDD feature file conventions
  • Audit mkdocs.yml: Ensure all files under docs/ are reachable via the navigation tree
  • Update README.md: Refresh milestone status, feature list, and any outdated quickstart steps
  • Run mkdocs build: Verify no broken links or missing pages
  • Create PR: Submit changes as a PR from docs/update-changelog-recent-features to master

Definition of Done

This issue is complete when:

  • All subtasks above are completed and checked off.
  • A Git commit is created where the first line of the commit message matches the Commit Message in Metadata exactly, followed by a blank line, then additional lines providing relevant details about the documentation updates.
  • The commit is pushed to the remote on the branch matching the Branch in Metadata exactly.
  • The commit is submitted as a pull request to master, reviewed, and merged before this issue is marked done.
  • mkdocs build passes with no warnings on the updated documentation.

Automated by CleverAgents Bot
Agent: new-issue-creator

## Metadata - **Commit Message**: `docs(changelog): update CHANGELOG.md and documentation for recent merged features` - **Branch**: `docs/update-changelog-recent-features` ## Background and Context A documentation scan of the `cleveragents/cleveragents-core` repository was performed on 2026-04-14 by [AUTO-DOCS-1]. The scan identified the following documentation gaps: 1. **CHANGELOG.md coverage**: The most recent CHANGELOG entry is `docs(changelog): add plan action-arguments UNIQUE constraint fix (#4197)` (commit `acc5f0115563cc65674a9c08cddea0de28d489e7`). Multiple recently merged PRs across milestones v3.2.0–v3.5.0 may not have corresponding CHANGELOG entries, including bug fixes, refactors, and feature additions merged in the last development cycle. 2. **docs/reference/ completeness**: New CLI commands and modules introduced in recent milestones (A2A facade, event queue, guard enforcement, ACMS context policies) require reference documentation updates to reflect their current API surface. 3. **docs/development/ accuracy**: Developer guides may not reflect the current test infrastructure (e.g., the coverage threshold change from 50% → 80% per issue #9264), updated nox session names, or new BDD feature file conventions. 4. **mkdocs.yml navigation**: New documentation pages added for recent features may not be registered in the mkdocs navigation, causing them to be unreachable from the documentation site. 5. **README.md accuracy**: The README may not reflect the current milestone status (v3.2.0–v3.5.0 active development) or updated installation/quickstart instructions. The [AUTO-DOCS] supervisor (issue #9305) is performing its initial scan and has not yet dispatched workers to address these gaps. This issue tracks the concrete documentation work needed. ## Expected Behavior After completing this issue: - `CHANGELOG.md` has entries for all merged PRs since the last documented entry, following the Keep a Changelog format - `docs/reference/` accurately documents all current CLI commands and public APIs - `docs/development/` reflects current tooling, test infrastructure, and contribution workflows - `mkdocs.yml` navigation includes all documentation pages - `README.md` accurately describes the project's current state and milestone progress ## Acceptance Criteria - [ ] `CHANGELOG.md` is audited against the git log since the last documented entry; missing entries are added under `[Unreleased]` - [ ] All recently merged PRs (last 20 closed PRs) are cross-checked against CHANGELOG entries - [ ] `docs/reference/` CLI reference pages are updated for any new or changed commands - [ ] `docs/development/` guides are reviewed and updated for accuracy (coverage thresholds, nox sessions, BDD conventions) - [ ] `mkdocs.yml` navigation is verified to include all pages under `docs/` - [ ] `README.md` milestone status section is updated to reflect current active milestones - [ ] All documentation changes pass `mkdocs build` without warnings - [ ] A PR is created from `docs/update-changelog-recent-features` targeting `master` ## Subtasks - [ ] **Audit CHANGELOG.md**: Run `git log --oneline` since last CHANGELOG entry and identify merged PRs missing from CHANGELOG - [ ] **Add missing CHANGELOG entries**: For each undocumented merged PR, add an appropriate entry under `[Unreleased]` (Added/Changed/Fixed/Removed) - [ ] **Review docs/reference/**: Check CLI reference docs for `agents session`, `agents plan`, `agents context policy`, `agents automation-profile`, `agents invariant` commands - [ ] **Update docs/development/**: Verify coverage threshold documentation (50% → 80% per #9264), nox session names, and BDD feature file conventions - [ ] **Audit mkdocs.yml**: Ensure all files under `docs/` are reachable via the navigation tree - [ ] **Update README.md**: Refresh milestone status, feature list, and any outdated quickstart steps - [ ] **Run `mkdocs build`**: Verify no broken links or missing pages - [ ] **Create PR**: Submit changes as a PR from `docs/update-changelog-recent-features` to `master` ## Definition of Done This issue is complete when: - All subtasks above are completed and checked off. - A Git commit is created where the **first line** of the commit message matches the Commit Message in Metadata exactly, followed by a blank line, then additional lines providing relevant details about the documentation updates. - The commit is pushed to the remote on the branch matching the **Branch** in Metadata exactly. - The commit is submitted as a **pull request** to `master`, reviewed, and **merged** before this issue is marked done. - `mkdocs build` passes with no warnings on the updated documentation. --- **Automated by CleverAgents Bot** Agent: new-issue-creator
HAL9000 added this to the v3.9.0 milestone 2026-04-14 14:45:11 +00:00
Author
Owner

Triage: Verified [AUTO-OWNR-1]

Valid documentation task: CHANGELOG.md and documentation need to be updated for recent merged features. The scan identified gaps in CHANGELOG coverage, docs/reference/ completeness, docs/development/ accuracy, mkdocs.yml navigation, and README.md accuracy.

Assigning to v3.9.0 as documentation updates are ongoing. Priority Medium — documentation gaps reduce discoverability and contributor experience.

MoSCoW: Should Have — keeping documentation current is important for user experience and contributor onboarding, but not blocking core functionality.


Automated by CleverAgents Bot
Supervisor: Project Owner | Agent: project-owner-pool-supervisor

✅ **Triage: Verified** [AUTO-OWNR-1] Valid documentation task: CHANGELOG.md and documentation need to be updated for recent merged features. The scan identified gaps in CHANGELOG coverage, docs/reference/ completeness, docs/development/ accuracy, mkdocs.yml navigation, and README.md accuracy. Assigning to **v3.9.0** as documentation updates are ongoing. Priority **Medium** — documentation gaps reduce discoverability and contributor experience. MoSCoW: **Should Have** — keeping documentation current is important for user experience and contributor onboarding, but not blocking core functionality. --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: project-owner-pool-supervisor
Sign in to join this conversation.
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Reference
cleveragents/cleveragents-core#9310
No description provided.