From f3a21a7ae6a3ee9a2c9dbee229e98c59f8877c2d Mon Sep 17 00:00:00 2001 From: CleverThis Date: Thu, 9 Apr 2026 07:58:04 +0000 Subject: [PATCH] docs: update CHANGELOG, automation-tracking agent prefixes, and add invariant-reconciliation module doc MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - CHANGELOG.md [Unreleased]: add entries for comprehensive worker tracking system, centralized automation-tracking-manager subagent, plan action argument upsert (#4174), product-builder tracking migration, implementation orchestrator scaling to 32 workers, CI lint fix, CI integration test fix (#5266), orchestrator worker dispatch fix - docs/development/automation-tracking.md: extend agent prefix and reporting interval tables to cover all 16 supervisors (product-builder, architect, timeline-updater, docs-writer, architecture-guard, continuous-pr-reviewer, uat-tester, project-owner); add Forgejo search examples for all new prefixes - docs/modules/invariant-reconciliation.md (new): module guide for the built-in InvariantReconciliationActor introduced in v3.8.0 — covers algorithm, automatic invocation, key classes, DI registration, error handling, and usage examples --- CHANGELOG.md | 42 ++++++ docs/development/automation-tracking.md | 24 ++++ docs/modules/invariant-reconciliation.md | 175 +++++++++++++++++++++++ 3 files changed, 241 insertions(+) create mode 100644 docs/modules/invariant-reconciliation.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 885d0e7ba..a1877da6c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -34,12 +34,54 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). PR–issue label synchronization. The `issue-state-updater` syncs PR state labels whenever issue states change. +- **Comprehensive Worker Tracking System**: All 16 supervisors now provide detailed + visibility into worker activities and health. Enhanced `product-builder`, + `implementation-orchestrator`, `continuous-pr-reviewer`, and `uat-tester` with + detailed session monitoring via the OpenCode API. Added actual cycle-time calculation + using timestamps, stale worker detection and restart, and proper tracking issue + lifecycle (delete previous, create new each cycle). Tracking extended to previously + uncovered supervisors: `architect`, `timeline-updater`, `docs-writer`, + `architecture-guard`. + +- **Centralized Automation Tracking Manager**: New `automation-tracking-manager` + subagent acts as the single source of truth for all tracking operations. Migrated + 7 key agents (`system-watchdog`, `implementation-orchestrator`, `timeline-updater`, + `project-owner`, `product-builder`, `backlog-groomer`, and others) to use the + centralized manager. Fixes cycle-skipping and duplicate-issue bugs; ensures + sequential cycle numbers persist across agent restarts. + +- **Plan Action Argument Upsert**: `PlanLifecycleService` now upserts action arguments + during `plan use` to avoid `UNIQUE` constraint violations when reusing actions. + Includes batch-delete update with identity-map eviction, invariants unique constraint, + and an Alembic migration. (#4174) + ### Changed - **Automation Tracking Format**: All automation tracking issues now use a standardized header format with mandatory `Reporting Interval: (Next report expected: )` declarations, enabling precise staleness detection. +- **Product-Builder Tracking Migration**: `product-builder` now creates individual + per-cycle tracking issues (prefix `AUTO-PROD-BLDR`) instead of a long-running shared + session state issue. Each cycle closes the previous tracking issue and creates a fresh + one, providing better isolation and traceability. + +- **Implementation Orchestrator Scaling**: Scaled to 32 parallel workers. Reduced + dispatch loop sleep from 10s to 2s, simplified worker verification, reduced retry + delays from 15s to 2s, and reduced idle sleep from 60s to 10s for dramatically + faster throughput. + +### Fixed + +- **CI Lint**: Resolved 51 ruff violations in `scripts/validate_automation_tracking.py` + (import ordering, deprecated `typing` generics, unused imports, line-length, whitespace). +- **CI Integration Tests**: Removed stale `tdd_expected_fail` tag from + `robot/coverage_threshold.robot` — the underlying bug (issue #4305) is resolved and + the tag was inverting a passing test to a failure. (#5266) +- **Orchestrator Worker Dispatch**: Fixed `verify_worker_started()` to handle the dict + response format from the OpenCode API `/session/status` endpoint instead of an array. + Workers now dispatch and verify correctly, preventing incorrect session deletion. + --- ## [3.8.0] — 2026-04-05 diff --git a/docs/development/automation-tracking.md b/docs/development/automation-tracking.md index 6711acc9f..4b3a56c1d 100644 --- a/docs/development/automation-tracking.md +++ b/docs/development/automation-tracking.md @@ -44,6 +44,14 @@ For emergency announcements or important messages: | system-watchdog | `AUTO-WATCHDOG` | `[AUTO-WATCHDOG] System Health (Cycle 8)` | | backlog-groomer | `AUTO-GROOMER` | `[AUTO-GROOMER] Grooming Report (Cycle 23)` | | human-liaison | `AUTO-LIAISON` | `[AUTO-LIAISON] Status Update (Cycle 67)` | +| product-builder | `AUTO-PROD-BLDR` | `[AUTO-PROD-BLDR] Build Session (Cycle 5)` | +| architect | `AUTO-ARCH` | `[AUTO-ARCH] Architecture Report (Cycle 3)` | +| timeline-updater | `AUTO-TIMELINE` | `[AUTO-TIMELINE] Timeline Update (Cycle 12)` | +| docs-writer | `AUTO-DOCS` | `[AUTO-DOCS] Documentation Report (Cycle 7)` | +| architecture-guard | `AUTO-ARCH-GUARD` | `[AUTO-ARCH-GUARD] Guard Report (Cycle 9)` | +| continuous-pr-reviewer | `AUTO-PR-REVIEW` | `[AUTO-PR-REVIEW] Review Status (Cycle 4)` | +| uat-tester | `AUTO-UAT` | `[AUTO-UAT] UAT Status (Cycle 6)` | +| project-owner | `AUTO-PROJ-OWN` | `[AUTO-PROJ-OWN] Owner Status (Cycle 11)` | ## Required Labels @@ -74,6 +82,14 @@ This enables automated health monitoring by the system-watchdog to detect stalle | human-liaison | Status Update | Every 20 minutes (10 cycles) | Human activity monitoring | | system-watchdog | Health Report | Every 30 minutes (6 cycles) | System-wide health check | | session-persister | Checkpoint | Event-driven (variable) | After significant state changes | +| product-builder | Build Session | Every 10 cycles (~variable timing) | Full build session status | +| architect | Architecture Report | Every 10 cycles (~variable timing) | Architecture supervision status | +| timeline-updater | Timeline Update | Every 10 cycles (~variable timing) | Timeline maintenance status | +| docs-writer | Documentation Report | Every 10 cycles (~3.3 hours) | Documentation update status | +| architecture-guard | Guard Report | Every 10 cycles (~variable timing) | Codebase coherence check | +| continuous-pr-reviewer | Review Status | Every 10 cycles (~variable timing) | PR review pool status | +| uat-tester | UAT Status | Every 10 cycles (~variable timing) | UAT testing progress | +| project-owner | Owner Status | Every 10 cycles (~variable timing) | Project ownership decisions | ### Automated Health Monitoring @@ -267,6 +283,14 @@ label:"Automation Tracking" [AUTO-IMP-POOL] in:title label:"Automation Tracking" [AUTO-WATCHDOG] in:title label:"Automation Tracking" [AUTO-GROOMER] in:title label:"Automation Tracking" [AUTO-LIAISON] in:title +label:"Automation Tracking" [AUTO-PROD-BLDR] in:title +label:"Automation Tracking" [AUTO-ARCH] in:title +label:"Automation Tracking" [AUTO-TIMELINE] in:title +label:"Automation Tracking" [AUTO-DOCS] in:title +label:"Automation Tracking" [AUTO-ARCH-GUARD] in:title +label:"Automation Tracking" [AUTO-PR-REVIEW] in:title +label:"Automation Tracking" [AUTO-UAT] in:title +label:"Automation Tracking" [AUTO-PROJ-OWN] in:title ``` **Recent tracking issues (last 24 hours):** diff --git a/docs/modules/invariant-reconciliation.md b/docs/modules/invariant-reconciliation.md new file mode 100644 index 000000000..6a51260ab --- /dev/null +++ b/docs/modules/invariant-reconciliation.md @@ -0,0 +1,175 @@ +# Invariant Reconciliation Module + +**Package:** `cleveragents.actor.reconciliation` +**Introduced:** v3.8.0 + +The Invariant Reconciliation Actor is a built-in actor that automatically runs at +every plan phase transition to ensure all active invariants are consistent and +correctly prioritised before any strategy or execution work begins. + +For the invariant data model and scope hierarchy, see +[`docs/reference/invariants.md`](../reference/invariants.md). +For the `InvariantService` API, see +[`docs/api/core.md`](../api/core.md). + +--- + +## Purpose + +Invariants are natural-language constraints on plan execution that can be defined +at four scopes: global, project, action, and plan. When multiple invariants apply +to the same plan, conflicts can arise — for example, a project-level invariant may +contradict a plan-level one. The reconciliation actor resolves these conflicts +deterministically using a precedence chain and records each decision in the audit +trail. + +--- + +## Automatic Invocation + +`PlanLifecycleService` automatically invokes the reconciliation actor at the start +of three phase transitions: + +| Transition | Method | +|------------|--------| +| Strategize start | `start_strategize()` | +| Execute start | `execute_plan()` | +| Apply start | `apply_plan()` | + +If reconciliation fails, the phase transition is **blocked** with +`ReconciliationBlockedError` and an `INVARIANT_VIOLATED` event is emitted on the +event bus. The transition cannot proceed until the invariants are corrected. + +Post-correction reconciliation runs automatically via a `CORRECTION_APPLIED` event +subscription (best-effort; does not block correction completion). + +--- + +## Reconciliation Algorithm + +The actor follows a six-step algorithm (spec §19440–19600): + +1. **Collect** invariants from all four scopes: global, project, action, plan. +2. **Group** by normalised text (case-insensitive, stripped). +3. **Detect conflicts** — same text at different scopes, or contradictory constraints + that cannot be automatically resolved. +4. **Resolve** using specificity precedence: + ``` + plan > action > project > global + ``` + Exception: `non_overridable` global invariants always win regardless of scope. +5. **Record** an `invariant_enforced` decision for each active invariant in the + decision service. +6. **Return** a `ReconciliationResult` containing the reconciled `InvariantSet` and + all conflict records. + +--- + +## Key Classes + +### `InvariantReconciliationActor` + +```python +from cleveragents.actor.reconciliation import InvariantReconciliationActor + +actor = InvariantReconciliationActor( + invariant_service=container.invariant_service(), + decision_service=container.decision_service(), +) +result = actor.run(plan_id="...", project_name="...", action_name="...") +``` + +| Method | Description | +|--------|-------------| +| `run(plan_id, project_name, action_name) → ReconciliationResult` | Execute reconciliation for the given plan context | + +### `ReconciliationResult` + +Frozen dataclass returned by `InvariantReconciliationActor.run()`. + +| Field | Type | Description | +|-------|------|-------------| +| `reconciled_set` | `InvariantSet` | The final effective set of invariants | +| `conflicts` | `list[ConflictRecord]` | All detected conflicts with resolution details | +| `enforced_decision_ids` | `list[str]` | ULIDs of `invariant_enforced` decisions recorded | + +### `ConflictRecord` + +Frozen dataclass describing a single resolved conflict. + +| Field | Type | Description | +|-------|------|-------------| +| `key` | `str` | Normalised invariant text used for grouping | +| `winner` | `Invariant` | The invariant that prevailed after resolution | +| `losers` | `list[Invariant]` | Invariants that were overridden | +| `reason` | `str` | Human-readable explanation of the resolution | + +--- + +## DI Registration + +`InvariantService` is registered as a **Singleton** provider in the DI container: + +```python +from cleveragents.application.container import Container + +container = Container() +invariant_service = container.invariant_service() +``` + +Never construct `InvariantService` directly — always resolve it from the container. + +--- + +## Error Handling + +| Exception | When raised | +|-----------|-------------| +| `ReconciliationBlockedError` | Reconciliation fails; phase transition is blocked | + +When `ReconciliationBlockedError` is raised: +- The `INVARIANT_VIOLATED` event is emitted on the event bus. +- The phase transition is aborted. +- The plan remains in its current phase until the invariant conflict is resolved. +- Once resolved, a `CORRECTION_APPLIED` event triggers a best-effort re-run. + +--- + +## Usage Example + +```python +from cleveragents.application.container import Container +from cleveragents.actor.reconciliation import InvariantReconciliationActor + +container = Container() + +actor = InvariantReconciliationActor( + invariant_service=container.invariant_service(), + decision_service=container.decision_service(), +) + +result = actor.run( + plan_id="01HXYZ...", + project_name="my-project", + action_name="refactor-auth", +) + +# Inspect the reconciled invariant set +for inv in result.reconciled_set.invariants: + print(f"[{inv.scope}] {inv.text}") + +# Inspect conflicts +for conflict in result.conflicts: + print(f"Conflict: {conflict.key!r}") + print(f" Winner: [{conflict.winner.scope}] {conflict.winner.text}") + print(f" Reason: {conflict.reason}") +``` + +--- + +## Related Documentation + +- [Invariants reference](../reference/invariants.md) — data model, scope hierarchy, merge semantics +- [Plan Lifecycle](../architecture.md#plan-lifecycle) — phase transitions and gating +- [Decision Service](../reference/decision_service.md) — audit trail for enforced decisions +- [Architecture Overview](../architecture.md#invariant-reconciliation) — system-level context -- 2.52.0