Created docs/development/contributor-guide.md with comprehensive practical workflow guidance covering prerequisites, fork/clone workflow, branch naming, commit format, pre-commit hooks, test suite, BDD test writing, code style, type checking, ADR process, PR checklist, and review process.
Extended README.md Documentation section with a Documentation Index table linking all major documentation resources. All existing README content preserved intact.
Document changes from PRs merged 2026-04-03 through 2026-04-05:
- CHANGELOG: add entries for CI artifact capture (#2782), ASV provider
benchmarks (#3022), CI quality gate restoration (#2629), plan list
--namespace option (#2616), and MCP 1.4.0 error extraction fix (#2600)
- docs/api/mcp.md: document MCP 1.4.0 error extraction from content[0].text
in MCPToolAdapter.invoke() with protocol note and usage example
- docs/reference/plan_cli.md: add --namespace/-n option to agents plan list
options table, update Filters panel description, add usage examples
- docs/development/ci-cd.md: document CI artifact capture for all 8 nox jobs,
artifact naming convention, retention policy, and agent integration
- Add docs/development/ci-incident-runbook.md: comprehensive runbook for
diagnosing, triaging, and recovering from master branch CI quality gate
failures. Covers all 11 jobs in the status-check gate, triage procedures
per failure type, the fix branch workflow, and the complete list of
prohibited suppression techniques.
- Update docs/development/ci-cd.md: expand the Required Status Checks table
to include all 11 jobs (e2e_tests and helm were previously missing), update
the CI job dependency graph to reflect the actual status-check consolidation
gate, add a cross-reference to the new incident runbook, and strengthen the
no-direct-pushes-to-master note.
- Update docs/development/quality-automation.md: expand the CI Jobs table to
include integration_tests, e2e_tests, and the status-check consolidation
gate, which were previously missing.
- Update mkdocs.yml: add CI Incident Runbook to the Development nav section.
- Update CHANGELOG.md: record the documentation fix under [Unreleased].
ISSUES CLOSED: #2597
- plan_cli.md: add warning admonition for legacy/v3 plan workflow mixing
detection (#1577) — agents plan commands now reject mixed legacy+v3 usage
- ci-cd.md: document pre-migrated database template optimization (#2334)
— all test suites now use CLEVERAGENTS_TEMPLATE_DB to skip redundant
Alembic migrations; slow_integration_tests upgraded to pabot
Restore original permission structure and model configuration while adding
only the changes needed for issue #7521: forgejo_update_pull_request
permission and PR Workflow for Major Changes documentation section.
Fixes addressed:
- Restore flat permission format (was incorrectly restructured to nested)
- Restore model to claude-haiku-4-5 with reasoningEffort max
- Restore removed critical rules (6: label delegation, 7: pagination)
- Restore removed permission denials (*, doom_loop, question, etc.)
- Add CHANGELOG.md entry for this feature
- Restore CONTRIBUTORS.md to master (remove unrelated changes)
ISSUES CLOSED: #7521
# Conflicts:
# CONTRIBUTORS.md
Extract the benchmark-regression job from the default PR CI workflow
into a dedicated scheduled workflow (.forgejo/workflows/benchmark-scheduled.yml).
The benchmark job was blocking PR feedback for 99-132 minutes even when
lint/typecheck/tests passed in under 20 minutes. The new workflow runs:
- Nightly regression tests (2 AM UTC) comparing HEAD against master
- Weekly full benchmark suite (3 AM UTC Sundays) for trend analysis
- Manual dispatch trigger for ad-hoc benchmark validation
AWS S3 integration stores benchmark results for historical trend analysis.
Documentation updated in docs/development/ci-cd.md.
CONTRIBUTORS.md updated with benchmark workflow separation contribution.
ISSUES CLOSED: #9040
# Conflicts:
# CONTRIBUTORS.md
# Conflicts:
# CONTRIBUTORS.md
Move alembic configuration and migration files from repository root into the
Python package structure to ensure they are included in the wheel distribution.
This fix resolves the FileNotFoundError when running `agents init` in Docker
containers or any environment using the built wheel distribution.
Changes:
- Move alembic/ directory from repo root to
src/cleveragents/infrastructure/database/migrations/
- Move alembic.ini to the same new location and update script_location setting
- Update MigrationRunner._find_alembic_ini() to search from the new canonical
location within the package
- Update create_template_db.py to point to the new alembic.ini location
- Update documentation references to reflect new migration file locations
- Create __init__.py for migrations package
- The env.py file is imported when running tests that verify all modules can be
imported without errors. However, context.config is only available when alembic
is actually running migrations, not during normal module imports. This caused
an AttributeError when the test tried to import the migrations.env module.
- Fix by using getattr() with a default value to safely access context.config,
and guard all code that uses config with None checks. This allows the module
to be safely imported while still functioning correctly during migrations.
Testing:
- Verified MigrationRunner can locate alembic.ini in new location
- Tested agents init succeeds in creating project with database
- Template database creation works correctly
- All migration tests should pass without changes
Alembic files now follow standard Python packaging conventions, making them
automatically included in wheel distributions without special configuration.
ISSUES CLOSED: #4180
Renamed backlog-grooming-pool-supervisor to grooming-pool-supervisor and
backlog-grooming-worker to grooming-worker. The grooming agents now analyze
all open issues AND pull requests (not just the backlog). Workers perform a
full 10-point quality analysis on a single item instead of processing
batches. PRs with unaddressed reviews are prioritized. PR labels are synced
from linked issues. Workers post [GROOMED] markers for tracking.
Fixed critical issue: implementation-pool-supervisor now correctly dispatches
workers through tier selectors (tier-haiku/codex/sonnet/opus) instead of
launching implementation-worker directly, ensuring the escalation model
actually sets the correct model tier. Added implementation-worker to all
four tier selector task permissions.
Updated session tags from AUTO-BLOG to AUTO-GROOM. Updated specification
sections 4.2.1, 5.5, 5.5.1, 9.7, and architecture diagram.
ISSUES CLOSED: n/a
Add comprehensive responsibility-first analysis of the entire agent system
covering 144 named responsibilities (R-01 through R-144) organized into 8
categories with 29 sub-categories and complete bidirectional cross-references.
Key additions:
- Section 22.0: Categorized Responsibility Index with navigation guide
- Section 7.9: Universal Supervisor Responsibilities (13 shared baseline)
- Section 22.145: Redundancy Analysis Summary with depth distribution,
highest-redundancy items, most cross-referenced agents, and 5 named
redundancy patterns
- 30 agent back-reference tables covering ~50 individual agents
- Category introductions explaining scope and significance
- 6th foundational principle (Defense-in-Depth) added to Section 1.1
Categories: A (Development Lifecycle, 50 items), B (Quality Assurance),
C (Ticket Hygiene), D (Architecture), E (Operational Health),
F (Human Interaction), G (Strategic Governance), H (Project Standards).
ISSUES CLOSED: N/A
- Fixed duplicate section number: two §2.4 -> renamed first to §2.3.1
- Verified all section cross-references valid
- Verified Appendix A model/mode data matches frontmatter (10 samples)
- Verified mkdocs.yml navigation entry
- Comprehensive stale-name sweep: zero hits across all files
- Added v1.36.0 revision entry with final statistics
- Added FORGEJO_REVIEWER_PASSWORD to Section 6.17 env table and Appendix C
- Purged all remaining "self-approval"/"shared bot account" language from spec
- Updated Sections 8.3.2 and 8.3.3 for dual-account architecture
- Added v1.31.0 revision entry
- Added v1.27.0 entry: all 17 agents fixed with correct READ-before-CREATE order
- All agents now include rolling average interval defaults and Estimated Cycle Interval requirement
- 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.
- 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 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.
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).
The TLS handshake failure on git.dev.cleveragents.com was caused by the
hostname being absent from the certificate's Subject Alternative Names
(SANs), or by SNI virtual-host misconfiguration on the server side.
This commit delivers the repository-side remediation:
- scripts/check-tls-cert.py: New TLS certificate health-check script.
Connects to a hostname, verifies the certificate's SANs include the
target hostname, checks expiry, and reports errors/warnings. Accepts
an injectable SSLContext for unit testing without real network access.
Supports wildcard SAN matching and configurable expiry warning threshold.
- docs/development/ops-runbook.md: New ops runbook documenting the full
certificate renewal procedure (Let's Encrypt/certbot and manual CA),
SNI misconfiguration diagnosis steps, expiry monitoring with cron, and
recommended alert thresholds (30/14/7/0 days).
- features/tls_certificate_check.feature: 14 Behave scenarios tagged
@tdd_issue @tdd_issue_1543 covering: missing SAN detection, valid SAN
acceptance, expired certificate detection, expiry warning threshold,
TLS handshake errors, connection timeouts, connection refused, wildcard
SAN matching, and _hostname_matches_san unit tests.
- features/steps/tls_certificate_check_steps.py: Step definitions for
the above feature, using unittest.mock to inject SSL contexts and
socket connections so no real network calls are made.
- mkdocs.yml: Added Ops Runbook to the Development section navigation.
The actual server-side certificate renewal (adding git.dev.cleveragents.com
as a SAN and reloading the web server) must be performed by the server
administrator following the procedure in docs/development/ops-runbook.md.
Closes#1543
ISSUES CLOSED: #1543
Root cause: actions/checkout@v4 was not configured with explicit write
credentials (token + persist-credentials), and no git user identity
(user.name/user.email) was set. Both are required for any git push
operation in Forgejo Actions.
Changes:
- release.yml create-release job: add token: secrets.FORGEJO_TOKEN and
fetch-depth: 0 to checkout; add 'Configure git identity for push
operations' step using HTTPS credential store; add 'Smoke-test push
access' step that validates write permission via Forgejo API before
any push attempt
- ci.yml: add push-validation job that validates push credentials on
every CI run using FORGEJO_TOKEN, including credential helper
verification and API-based write permission check; add push-validation
to status-check needs and result reporting
- docs/development/ci-cd.md: add FORGEJO_TOKEN, FORGEJO_URL, and
CONTAINER_REGISTRY* secrets to the secrets table; add 'Repository
Push Authentication' section documenting root cause, fix pattern,
smoke-test step, setup instructions, and security notes; add
push-validation to CI job dependency graph and quality gates table
Design decisions:
- HTTPS token authentication (not SSH deploy keys) -- simpler to manage
- ~/.git-credentials with chmod 600 for ephemeral, secure storage
- Smoke-test validates write permission via API before push attempts
- push-validation job is independent (no needs) -- runs in parallel
- No hardcoded credentials -- all secrets via Forgejo Secrets
ISSUES CLOSED: #1541
Renames `plan lifecycle-list` to `plan list` and `plan lifecycle-apply` to `plan apply` to align with the specification's canonical command names. Removes legacy V2 plan commands that occupied those names.
- Renamed CLI command registrations from lifecycle-list/lifecycle-apply to list/apply
- Removed legacy V2 apply and list commands (~200 lines)
- Updated apply shortcut in main.py to delegate to v3 lifecycle
- Added defensive null check for plan existence in apply command
- Updated 63+ test, doc, and benchmark files for consistency
Closes#881
Co-authored-by: Jeffrey Phillips Freeman <the@jeffreyfreeman.me>
Co-committed-by: Jeffrey Phillips Freeman <the@jeffreyfreeman.me>
The A2A facade now exposes 42 operations (31 extension + 11 legacy)
after the spec-aligned _cleveragents/ extension methods were added.
Update the BDD assertion and docs to match the actual count.
HAL9000
Repo Isolator
freemo
CoreRasurae
clever-agent