- Fixed broken Section 20.4 reference (section was removed in v1.16.0)
- Fixed wrong Section 13.2 reference (should be Section 11.2 for escalation)
- Replaced stale stale-check work type with awaiting-review in Section 10.1
- Added v1.19.0 revision entry
- Fixed build-opencode model in Appendix A from (not specified) to claude-sonnet-4-6
- Added v1.18.0 revision entry documenting 6 functional bugs fixed in agent definitions
- Adds a comprehensive specification for the autonomous agent system.
- Details the intended behavior, interactions, and design of all agents.
- Includes Kroki-based diagrams for workflows and interactions.
- Serves as the source of truth for agent implementation.
The MCPToolAdapter execute() section now documents the MCP 1.4.0 error
response protocol: when isError is true, the error message is extracted
from content[0].text rather than a non-standard top-level error key.
Falls back to 'unknown error' when content is absent or malformed.
This aligns the spec with the implementation fix in PR #2600 and the
approved proposal in issue #3330.
ISSUES CLOSED: #3330
- Update CONTRIBUTING.md to require only 1 approving review instead of 2
- Allow self-approval including for automated bot PRs (HAL9000)
- Approval can be formal review OR approval comment (LGTM, Approved, ✅)
- Remove distinction between human and bot PRs in review requirements
- Update agent definitions to reflect new policy
- Update system watchdog and documentation to match new requirements
This change unblocks PR merges while maintaining quality through CI checks
and still requiring at least one approval before merge.
- Fix automation-tracking.md to use new pool supervisor names
- Update session_state.md to reference implementation-pool-supervisor
- Fix pr-status-analyzer.md to reference pr-ci-test-fixer
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
clever-agent
HAL9000
freemo