The implementation (providers/registry.py line 519) uses 2024-05-01-preview
as the default Azure OpenAI API version, but the spec documented 2024-02-01.
The implementation's choice is correct — 2024-05-01-preview supports the
latest features including structured outputs and improved tool calling.
Update the spec to match the implementation and add guidance for users
who need a stable API version.
Fixes the discrepancy reported in UAT issue #5807.
Add a comprehensive Milestone Plan section to docs/specification.md
mapping architectural features to verifiable deliverables for each
milestone from v3.2.0 (Decisions + Validations + Invariants) through
v3.7.0 (TUI Implementation).
Each milestone section includes:
- Goal statement aligned with Forgejo milestone descriptions
- Spec coverage cross-references to existing spec sections
- Deliverables table with spec reference and verifiable check per item
- Key architectural constraints specific to that milestone
- Definition of Done criteria
Also adds:
- Cross-Milestone Quality Gates table (unit/integration/typecheck/lint/
coverage/security/performance/docs)
- Cross-Milestone Architectural Invariants (10 invariants that must hold
across all milestones)
This section serves as the authoritative mapping between the detailed
architectural spec and the milestone-level work tracked in Forgejo,
enabling implementers to understand which spec sections govern each
milestone's work and what constitutes completion.
Add cleveragents.providers to the API Reference module index table.
The providers.md page already exists but was missing from the index,
making it undiscoverable via the documentation navigation.
ISSUES CLOSED: #4940
Add comprehensive automated health monitoring and recovery capabilities
to the automation tracking system for proactive agent management.
**Major Enhancements:**
1. **Standardized Interval Reporting**
- Mandatory interval declaration in all tracking issues
- Format: 'Reporting Interval: <interval> (Next report expected: <timestamp>)'
- Enables precise staleness detection and recovery triggering
2. **Automated Health Monitoring (system-watchdog)**
- New audit_automation_tracking_health() function runs every 5 minutes
- Monitors all issues with 'Automation Tracking' label
- Detects stalled agents when >20% overdue from expected interval
- Calculates staleness ratios and time overdue metrics
3. **Automated Recovery System**
- Kills stalled agent sessions via OpenCode Server API (port 4096)
- Performs root cause analysis of session messages and agent definitions
- Creates high-priority diagnostic issues with detailed findings
- Automatically closes stale tracking issues with recovery notes
- Provides human-readable remediation recommendations
**Agent Updates with Standardized Format:**
- **implementation-orchestrator**: Status updates (5 cycles) + health reports (10 cycles)
- **backlog-groomer**: Grooming reports (5 min) + health reports (50 min)
- **human-liaison**: Status updates (20 min monitoring cycles)
- **session-persister**: Event-driven checkpoints with standardized format
- **system-watchdog**: Enhanced with comprehensive recovery capabilities
**Template Standardization:**
- Unified header format across all tracking issues
- Health indicators and next actions sections
- Consistent metadata and automation signatures
- Support for active/warning/error status indicators
**Documentation Updates:**
- Comprehensive automated recovery process documentation
- Agent interval reference table with all timing details
- Recovery issue format and diagnostic workflow
- Health check algorithm and staleness threshold explanation
**Benefits:**
- Proactive detection of crashed or stuck agents (20% staleness threshold)
- Automated recovery reduces manual intervention requirements
- Root cause analysis provides actionable diagnostic information
- Standardized format improves searchability and monitoring
- Comprehensive health metrics enable system-wide visibility
This enhancement transforms the automation tracking system from passive
logging to active health monitoring with automated recovery capabilities.
Adds a complete end-to-end walkthrough of the server connection CLI
commands and A2A protocol facade, verified by the UAT system with real
command outputs. Covers:
- agents server --help, connect, status, serve commands
- All output formats (rich, json, yaml, plain)
- A2A JSON-RPC 2.0 wire format (A2aRequest, A2aResponse, A2aEvent)
- A2aLocalFacade: 42 supported operations, stub mode, service wiring
- get_facade() wired to real DI container
- A2aVersionNegotiator: version negotiation and mismatch handling
- ServerConnectionConfig: validation rules
Also updates examples.json index with the new entry.
Adds a complete end-to-end walkthrough of the `agents db` command group,
verified by the UAT system with real command outputs. Covers:
- agents db --help (command discovery)
- agents db current (fresh database: 41 pending migrations listed)
- agents db history (full 41-revision DAG with branchpoints/mergepoints)
- agents db history --format json (structured DAG for scripting)
- agents db upgrade (applying all 41 migrations to head)
- agents db current --format json (CI/CD integration pattern)
- agents db downgrade -- -1 (relative rollback with -- separator)
- agents db downgrade <revision-id> (targeted rollback)
- agents db upgrade <revision-id> (targeted upgrade)
- agents db upgrade --format json (idempotent upgrade with JSON output)
Also updates examples.json index with the new entry.
Add the DEPENDENCY_ORDERED execution mode to the Child Plan Execution
Modes section. This mode performs topological sorting of subplan
dependencies and executes independent subplans concurrently in waves.
Also adds the dependency-ordered row to the failure handling table.
Closes#4034
Add skeleton_fragments field to the AssembledContext dataclass in the
spec to match the implementation (PR #3676). Update the pipeline
assemble() method signature to include skeleton_ratio and
parent_fragments parameters, and add Step 10 (SkeletonCompressor
invocation) to Phase 3 of the context assembly pipeline pseudocode.
Closes#3783
Add documentation for the four automatic checkpoint triggers
(on_tool_write, on_tool_write_complete, on_subplan_spawn, on_error)
that were implemented in PR #3474 and documented in the reference
doc (docs/reference/checkpointing.md) but missing from the main
specification.
Also adds the sandbox.checkpoint.auto-create-on config key to the
configuration reference table.
Closes#3784
Extend the UAT testing agents to capture successful test workflows and
automatically generate showcase documentation demonstrating real-world
usage of CleverAgents.
Key features added:
- Documentation generation when tests succeed end-to-end
- Intelligent duplicate detection to avoid redundant examples
- Categorization into cli-tools, api-clients, data-processing, testing-tools
- Automatic PR creation for new documentation examples
- Integration with existing UAT workflow without disruption
Documentation structure:
- New docs/showcase/ directory for real-world examples
- Category-specific subdirectories with README guides
- Example template for consistent formatting
- JSON index for tracking and duplicate detection
The UAT tester now serves dual purposes:
1. Finding bugs through comprehensive testing (existing behavior)
2. Generating high-quality documentation from successful test runs (new)
This enables the system to build its own showcase of capabilities while
performing regular quality assurance, providing valuable examples for
users and demonstrating the system's practical applications.
- docs/reference/plan_cli.md: add note about legacy/v3 plan workflow
mixing being disallowed (introduced in v3.8.0, issue #1577)
- docs/reference/uko_runtime.md: document v3.8.0 provenance tracking
(sourceResource, validFrom, isCurrent on typed triples) and revision
chain for temporal queries across indexing runs (issue #891)
- docs/reference/decision_correction.md: add CorrectionAttemptRecord
section documenting the correction_attempts table, state lifecycle,
repository API, and usage examples (issue #920)
- docs/modules/uko-provenance.md: new module guide for UKO provenance
tracking covering purpose, how provenance is attached, revision chain
mechanics, query patterns, persistence format, BDD coverage, and gotchas
- docs/api/tui.md: Document ShellDangerLevel, DangerousPattern, DEFAULT_PATTERNS,
DangerousPatternDetector, ShellSafetyService, and SafetyCheckResult with
full API reference, parameter tables, and usage examples
- docs/architecture.md: Add Invariant Reconciliation section covering the
builtin/invariant-reconciliation actor, four-scope algorithm, failure
behaviour, and DI registration
- README.md: Add Invariant Reconciliation, TUI shell danger detection, and
UKO provenance tracking to the Highlights section
ISSUES CLOSED: #3377
- Promote [Unreleased] CHANGELOG entries to [3.8.0] (2026-04-05)
- Add Shell Danger Detection section to docs/api/tui.md covering
ShellDangerLevel, DangerousPattern, ShellSafetyService, and
SafetyCheckResult with full API reference and usage examples
- Add InvariantService section to docs/api/core.md documenting
the new DI-registered singleton, its methods, and emitted events
- Update docs/architecture.md Plan Lifecycle section to document
invariant reconciliation as a phase transition gate
- Update README.md Highlights with shell danger detection, inline
permission questions, invariant reconciliation, UKO provenance
tracking, and JSON-RPC 2.0 A2A wire format
- Create docs/modules/shell-safety.md with full module guide
covering purpose, key classes, built-in patterns, custom pattern
registration, TUI integration, and testing guidance
ISSUES CLOSED: #1003#997#1391#1004#891#1501#1577#1941#2334
Per JSON-RPC 2.0 specification (Section 5.1), error codes must be integers.
This commit fixes the protocol compliance defect where A2aErrorDetail.code
was typed as str and error constants were string literals.
Changes:
- src/cleveragents/a2a/models.py: Change A2aErrorDetail.code from str to int;
update field_validator to only validate 'message' (code no longer needs
non-empty string check; Pydantic enforces int type)
- src/cleveragents/a2a/errors.py: Change all error code constants from string
literals to JSON-RPC 2.0 integer codes per docs/reference/a2a.md taxonomy:
NOT_FOUND = -32001, AUTH_ERROR = -32002, FORBIDDEN = -32003,
INVALID_STATE = -32004, PLAN_ERROR = -32008, CONFIGURATION_ERROR = -32009,
VALIDATION_ERROR = -32602, INTERNAL_ERROR = -32603
Update map_domain_error() return type from tuple[str, str] to tuple[int, str]
- features/steps/a2a_facade_steps.py: Update A2aErrorDetail construction to
map symbolic string names to integer codes via _CODE_MAP
- features/steps/a2a_facade_wiring_steps.py: Update error code assertion to
map symbolic names to integers for comparison
- features/steps/a2a_facade_coverage_boost_steps.py: Same as above
- features/steps/a2a_jsonrpc_wire_format_steps.py: Update all A2aErrorDetail
constructions and JSON-RPC dict payloads to use integer codes
- robot/helper_a2a_facade_wiring.py: Update wired_error_mapping() to compare
against integer codes
- robot/helper_a2a_jsonrpc_wire_format.py: Update response_error_wire_format()
to use integer code -32001 instead of string 'NOT_FOUND'
Wire format now produces {"code": -32001, ...} instead of {"code": "NOT_FOUND", ...},
making it compliant with JSON-RPC 2.0 and interoperable with standards-conformant clients.
ISSUES CLOSED: #2746
Final Day 95 timeline update (v3) with current Forgejo data as of 2026-04-05.
Key Changes:
- Open PRs: 92 → 170 (+78 new PRs from agent-driven activity)
- Open bugs: 536 → 809 (+273 new bugs from UAT/bug-hunt agents)
- Total open issues: 1547
- Session tracker: updated to #3377
- Milestone completions updated (all declined due to agent-driven issue creation outpacing closures)
- Gantt chart footer, update log, and both legend blocks updated
- Current Status Summary, Schedule Risk Summary, and Day 95 adherence entry all updated with final data
- New UAT bugs noted: #3444 (TUI HelpPanelOverlay keybinding mismatch), #3445 (plan rollback Rich output format incomplete)
Supersedes PR #3419 (docs/timeline-day95-v2) which had intermediate data.
Co-authored-by: Jeffrey Phillips Freeman <the@jeffreyfreeman.me>
Co-committed-by: Jeffrey Phillips Freeman <the@jeffreyfreeman.me>
Approved proposal: #3064
Changes:
- Glossary (line 92): Fix 3-tier precedence claim to correct 4-tier chain
(plan > action > project > global) and add non_overridable exception note
- Line 18980: Fix Invariant Reconciliation Actor step 5 precedence reference
- Line 18991: Fix Strategize phase invariant reconciliation precedence reference
- Lines 19601-19604: Update Precedence and conflict resolution section to include
action tier as a distinct scope (not promoted to plan tier) and add
non_overridable exception clause
- Line 19618: Fix invariant view calculation precedence reference
- Lines 19621+: Add Non-overridable global invariants documentation block
Rationale: The glossary and two Strategize-phase descriptions incorrectly stated
a 3-tier precedence chain (plan > project > global), contradicting ADR-016 which
defines a 4-tier chain (plan > action > project > global). The implementation in
actor/reconciliation.py and application/services/plan_lifecycle_service.py
correctly uses the 4-tier model. The non_overridable field on the Invariant domain
model was implemented but completely undocumented in the spec.
- docs/api/providers.md: new comprehensive API reference for
cleveragents.providers — ProviderRegistry, ProviderType,
ProviderCapabilities, ProviderInfo, LangChainChatProvider,
module-level helpers, environment variables, and ASV benchmarks
- docs/api/index.md: add providers module to module index table
- docs/architecture.md: add Provider Registry section with discovery,
selection, and factory usage examples
- CHANGELOG.md: add [Unreleased] entries for:
- agents plan list --namespace/-n option (#2616)
- ASV benchmark suite for providers module (#3022)
- MCP error extraction from content[0].text per MCP 1.4.0 (#2600)
- CI quality gates restored to passing on master (#2629)
Documents the agents plan errors CLI command in both the Command
Synopsis and Command Reference sections of the specification.
The command was already implemented in src/cleveragents/cli/commands/plan.py
and referenced in the TUI slash catalog but was absent from the CLI
documentation sections.
Changes:
- Command Synopsis: added 'agents plan errors <PLAN_ID>' after plan rollback
- Command Reference: added '##### agents plan errors' section with synopsis,
purpose, arguments, and Rich/Plain/JSON output examples
Approved via proposal issue #2883.
ISSUES CLOSED: #2883
Document the ca-system-watchdog continuous monitoring agent:
- All 12 audit descriptions with severity levels and detection patterns
- Session introspection via OpenCode Server API (Audits 6, 11, 12)
- Finding severity table and action dispatch table
- Health reporting format and configuration parameters
- Constraints and related documentation links
Add System Watchdog entry to mkdocs.yml Development nav section.
Covers commits 8c13e63c and 77427bd7 (system watchdog introduction
and deep session introspection enhancement).
Add DomainBaseModel section to docs/api/core.md documenting the shared Pydantic base class from PR #2014 (issue #1941), and add CHANGELOG entry for the CI template DB extension from PR #2399 (issue #2334).
ISSUES CLOSED: #1941
Co-authored-by: Jeffrey Phillips Freeman <jeffrey.freeman@cleverthis.com>
Co-committed-by: Jeffrey Phillips Freeman <jeffrey.freeman@cleverthis.com>
Add reference documentation for three new TUI features:
- docs/reference/tui_shell_safety.md: Full reference for the shell danger
detection subsystem (DangerousPatternDetector, ShellDangerLevel,
DangerousPattern, DangerousCommandWarning, DEFAULT_PATTERNS registry).
Covers all built-in patterns across CRITICAL/HIGH/MEDIUM/LOW levels,
usage examples, and custom pattern extension.
- docs/reference/tui_permission_question.md: Full reference for the inline
PermissionQuestionWidget (issue #997). Documents InlinePermissionQuestion,
PermissionRequestType, PermissionDecision, render_permission_question(),
PermissionDecisionEvent, and PermissionQuestionWidget with key bindings
and usage examples.
- docs/reference/tui.md: Extended with First-Run Experience section
(ActorSelectionOverlay, first_run helpers), Inline Permission Questions
section, shell danger detection note in Shell Mode, updated module table,
and links to new reference pages.
Add PermissionQuestionWidget API documentation to docs/api/tui.md including
method table, key bindings, PermissionDecisionEvent dataclass, and
render_permission_question() helper reference. Add corresponding CHANGELOG
entry under [Unreleased] Added section.
Refs: #997
HAL9000
freemo