cleveragents/cleveragents-core
4
0
Fork 3
Code Issues 6.0k Pull Requests 115 Actions Packages Projects Releases Wiki Activity

[AUTO-DOCS-3] docs: Add v3.4.0 ACMS and v3.5.0 Autonomy Hardening documentation #9709

Closed
HAL9000 wants to merge 18 commits from auto-docs-3-v340-v350 into main
pull from: auto-docs-3-v340-v350
merge into: cleveragents:main
Conversation 2 Commits 18 Files Changed 130
+7951 -877

18 Commits

Author SHA1 Message Date
HAL9000 b5b2662b07 docs: Add v3.4.0 ACMS and v3.5.0 Autonomy Hardening documentation 
- Add docs/context.md: ACMS v1 context management documentation
- Add docs/autonomy.md: Autonomy hardening and A2A protocol documentation
- Update CHANGELOG.md with v3.4.0 and v3.5.0 unreleased sections
- Update mkdocs.yml navigation

[AUTO-DOCS-3]
 2026-04-17 09:00:15 +00:00
HAL9000 d312590d60 fix(concurrency): protect validate_fragment_scope with lock and update CONTRIBUTORS 
- Wrapped validate_fragment_scope() body with self._lock to prevent
  RuntimeError: dictionary changed size during iteration when another
  thread mutates the tier stores during scope validation
- Updated CONTRIBUTORS.md to document HAL 9000's concurrency safety
  contributions including thread-safe context tier management (issue #7547)

Fixes review feedback from PR #8279.

ISSUES CLOSED: #7547
 2026-04-17 09:00:15 +00:00
HAL9000 79dc7fb1a3 fix(concurrency): add thread safety to ContextTierService 
Implemented thread-safety improvements for ContextTierService by
introducing a re-entrant lock and guarding all critical sections
with self._lock. This prevents RuntimeError: dictionary changed
size during iteration under concurrent plan execution.

- Added threading.RLock to ContextTierService.__init__ as self._lock
- Wrapped all public methods (store, get, promote, demote, evict_lru,
  get_metrics, get_all_fragments, get_hot_fragments, get_for_actor,
  get_scoped_view) with with self._lock:
- Added _lock: threading.RLock type stub to TierRuntimeMixin and
  ScopedTierMixin
- Wrapped enforce_staleness in TierRuntimeMixin with self._lock
- Wrapped get_scoped_by_resource and get_scoped_metrics in
  ScopedTierMixin with self._lock
- Extracted settings helpers to new context_tier_settings.py to keep
  context_tiers.py under 500 lines
- Added BDD feature file context_tier_thread_safety.feature with
  10 thread-safety scenarios
- Added step definitions context_tier_thread_safety_steps.py
- Updated CHANGELOG.md with fix entry

ISSUES CLOSED: #7547
 2026-04-17 09:00:15 +00:00
HAL9000 4487880ea6 fix(cli): --format color now emits ANSI-coloured output instead of plain text 
Route the COLOR format option through format_output_session (which uses
ColorMaterializer) instead of _format_plain. Previously --format color
produced identical output to --format plain because both were routed to
the same plain-text formatter. All other formats (plain, json, yaml,
rich, table) remain unaffected.

Updated CHANGELOG.md with the fix entry and CONTRIBUTORS.md with HAL 9000
contribution details.

ISSUES CLOSED: #7910
 2026-04-17 09:00:15 +00:00
HAL9000 5e2dd88beb fix(tests): fix create_template_db.py to create writable SQLite template database 
Added os.chmod(db_path, 0o664) after database creation to ensure the template
database has writable permissions. This prevents sqlite3.OperationalError: attempt
to write a readonly database when tests copy and modify the template during test
setup.

The template database is now created with rw-rw-r-- (664) permissions instead of
the default rw-r--r-- (644), allowing the test runner process to write to it.

ISSUES CLOSED: #9372
 2026-04-17 09:00:15 +00:00
HAL9000 2227329741 fix(cli): add missing "✓ OK" footer to agents plan errors rich output 
ISSUES CLOSED: #9355
 2026-04-17 09:00:15 +00:00
CleverAgents Build Agent 0a8d99a60e Build: sped up bootstrap time of pr-merge pool agent 2026-04-17 09:00:15 +00:00
CoreRasurae 66b1001bd6 feat(plan): implement LLM-powered strategy actor 
Implement StrategyActor class for the plan strategize phase that uses an
LLM to produce hierarchical execution strategies with dependencies,
resource requirements, estimated complexity, and risk scores.

Key components:
- StrategyActor: Core actor with LLM prompt construction, response
  parsing (JSON and numbered-list fallback), and graceful degradation
  to StrategizeStubActor when no LLM provider is configured
- StrategyAction/StrategyTree: Pydantic models for the hierarchical
  action tree with dependency links
- validate_no_cycles(): Kahns algorithm (deque-based) for dependency
  graph cycle detection, raising PlanError on circular dependencies
- build_strategy_prompt(): Context-aware prompt construction using
  definition_of_done, resources, project context, and ACMS analysis
  with XML-delimited user content sections for prompt injection
  hardening
- parse_strategy_response(): Robust LLM output parsing with JSON
  extraction and numbered-list fallback
- resolve_strategy_actor(): Integration point for the existing
  actor.default.strategy config key (CLEVERAGENTS_DEFAULT_STRATEGY_ACTOR)
- Decision conversion producing strategy_choice Decision objects
- build_decisions() preserves tree hierarchy via parent_id mapping,
  populates downstream_decision_ids from dependency edges, and
  validates plan_id

Structural tree hierarchy (B2 review fix):
- _build_tree infers parent_id from the dependency graph: each
  actions first resolved dependency becomes its structural parent.
  Actions with no dependencies fall back to the root.  This produces
  hierarchical trees for agents plan tree rendering per spec
  Plan Decision Tree.

Downstream decision tracking (B3 review fix):
- build_decisions populates downstream_decision_ids from the strategy
  trees dependency edges using a pre-generated decision_id map so
  influence relationships between decisions are recorded per the spec
  Decision Record Structure.

Post code-review hardening (PR #1175):
- Broadened exception handling in execute() and ACMS retrieval to
  catch all LLM provider errors (openai, httpx, anthropic, etc.)
  with graceful fallback to stub mode (H1, H2)
- Added warning log for unresolvable dependency references so
  dropped edges are visible in structured logs (H3)
- Added XML-delimited user content sections and explicit data-only
  instructions in system prompt for prompt injection hardening (H4)
- Switched prompt truncation to word-boundary-safe _truncate_at_word()
  for all prompt input sections (M1)
- Fixed _parse_actor_name to preserve user-specified provider or
  model when only one segment is empty, instead of discarding both (M2)
- Annotated _build_invariant_records as placeholder pending the
  Invariant Reconciliation Actor implementation (M5)
- Documented resources/project_context params as future-wired
  through PlanExecutor.run_strategize() (M8)
- Added docstring noting supersession relationship with
  LLMStrategizeActor in llm_actors.py (M9)
- Added __all__ export definition (L2)
- Improved validate_no_cycles docstring edge direction semantics (L7)
- Cap JSON parse retry loop at _MAX_JSON_PARSE_RETRIES (10)

Post second code-review hardening (PR #1175, review cycle 2):
- Fixed _truncate_at_word docstring: documented max_chars >= 3
  precondition for the result-length guarantee (R-H1)
- Added warning log in build_decisions for unresolvable parent_id
  references, matching the existing _build_tree warning for
  unresolvable dependency references (R-H2)
- Fixed _parse_actor_name to handle whitespace-only input by adding
  actor_name.strip() check alongside the emptiness check (R-M1)
- Tightened ACMS scenario assertions from non-empty to expected
  count of 5 decisions (R-L3)
- Added timeout=60s on_timeout=kill to all Robot test cases for
  consistency with project patterns (R-M5)

Post third code-review hardening (PR #1175, review cycle 3):
- Added _sanitize_xml_content() to escape XML special characters
  (<, >, &) in user content before embedding into XML-delimited
  prompt sections, preventing prompt injection via forged closing
  tags (spec Prompt Injection Mitigation) (CR3-M1)
- Upgraded _try_parse_json() to multi-anchor retry: collects all
  [{ positions left-to-right and tries each as a candidate start,
  fixing false-start anchoring when LLM preamble contains [{
  fragments before the real JSON array (CR3-M2)
- Added _truncate_at_word() guard for max_chars < 3: returns a
  hard slice instead of word-boundary truncation when the ellipsis
  would exceed the limit (CR3-L2)
- Changed _build_tree collision fallback key from -(idx+1) to
  -(1_000_000+idx) to eliminate theoretical collision with
  LLM-produced negative step numbers (CR3-L3)
- Added forward-looking API docstring note to build_decisions()
  documenting that it is not yet wired into PlanExecutor and will
  be integrated once Decision persistence lands (CR3-M3)

Post fourth code-review hardening (PR #1175, review cycle 4):
- Fixed _try_parse_json per-anchor retry counter: reset retries=0
  at the start of each anchor iteration so false-start [{ anchors
  in LLM preamble text no longer exhaust the retry budget for the
  correct anchor (CR4-B1)
- Added known-limitations docstring to module header documenting
  missing decision types (resource_selection, subplan_spawn,
  invariant_enforced) as future work (CR4-D1)
- Rewrote XML injection assertion in test to use regex extraction
  instead of fragile chained .split() calls that could IndexError
  on structural changes (CR4-T5)

Post fifth code-review hardening (PR #1175, review cycle 5):
- Added warning log in build_decisions for empty-string parent_id
  (distinct from None) so the silent fallback to root is visible
  in structured logs for debuggability (CR5-B1)
- Added plan_id propagation assertion to build_decisions test
  scenarios verifying decision.plan_id matches the input (CR5-T1)
- Added sequence_number monotonicity assertion verifying decision
  sequence_numbers are zero-indexed and monotonically increasing
  (CR5-T2)
- Added _truncate_at_word boundary test for max_chars=3 (exactly
  ellipsis length) verifying correct "..." output (CR5-T3)
- Tightened false-start anchor test from permissive len>=1 to
  specific description match "Sole real action" (CR5-T4)
- Added word-boundary truncation test using space-separated input
  to exercise the rfind(" ") path under oversized DoD (CR5-T5)

Post sixth code-review hardening (PR #1175, review cycle 6):
- Added _MAX_INVARIANTS cap (100) for invariant list truncation in
  prompt to prevent token limit overflows, consistent with other prompt
  section caps (CR6-M4)
- Added negative max_chars guard in _truncate_at_word returning empty
  string instead of slicing from end (CR6-M5)
- Added global JSON parse attempt cap _MAX_GLOBAL_JSON_ATTEMPTS (50)
  across all anchors in _try_parse_json (CR6-L3)
- Moved re import to module level in strategy_parsing.py per
  CONTRIBUTING import guidelines (CR6-L4)
- Extracted _DEFAULT_DESCRIPTION constant to eliminate duplication
  between _default_action() and _build_tree() (CR6-L5)

Post seventh code-review hardening (PR #1175, review cycle 7):
- Decoupled _execute_stub from StrategizeStubActor._parse_steps
  private method by delegating to parse_strategy_response, removing
  cross-class private method dependency (CR7-M1)
- Added ULID format validation on plan_id in execute() and
  build_decisions() for spec-consistent argument validation per
  §Plan glossary and CONTRIBUTING §Argument Validation (CR7-M2)
- Constrained StrategyAction.estimated_complexity to
  Literal["low", "medium", "high"] at Pydantic model level per
  CONTRIBUTING §Type Safety (CR7-M5)
- Documented XML-tag prompt boundary deviation from spec
  [USER_CONTENT_START]/[USER_CONTENT_END] markers with rationale
  for the more structured approach (CR7-M6)
- Added _build_tree empty-input guard comment documenting orphaned
  root_id semantics (CR7-L1)
- Added _truncate_at_word > 0 intent comment explaining why
  position-0 space is intentionally excluded (CR7-L2)
- Added build_decisions context_snapshot future-work comment
  referencing spec §Decision Record Structure (CR7-L5)
- Used enumerate() in _build_tree first loop for idiomatic
  Python (CR7-L7)
- Fixed false-start anchor test (CR5-T4) broken by CR6-L3 global
  cap: reduced preamble fragments from 15 to 3 so total attempts
  stay within _MAX_GLOBAL_JSON_ATTEMPTS (CR7-T1)
- Fixed test plan_ids containing non-Crockford-Base32 characters
  (L→K) to pass ULID format validation (CR7-T2)

Tests:
- 105 Behave BDD scenarios in features/strategy_actor_llm.feature
  adding: global JSON attempt cap exhaustion (CR7-L3), orphaned
  dependency edge silent drop (CR7-L4), non-ULID plan_id rejection
  in execute() and build_decisions() (CR7-M2)
- 101 Behave BDD scenarios in features/strategy_actor_llm.feature
  including new scenarios for _truncate_at_word edge cases (L3),
  create_llm argument verification (L4), non-numeric step field
  fallback (L5), updated assertions for XML-delimited prompts
  and _parse_actor_name partial-segment preservation (M2),
  lifecycle exception fallback (R1), PydanticValidationError
  re-raise verification (R2), self-loop cycle detection (R3),
  whitespace-only actor name (R4), XML tag injection sanitisation
  (CR3-M1), preamble bracket fragment parsing (CR3-M2),
  _truncate_at_word sub-3 limit (CR3-L2), resolve_strategy_actor
  with both llm config and registry (CR3-L5), build_decisions
  unresolvable parent_id fallback (CR3-L7), XML injection in
  resources/project_context/acms_context fields (CR4-S1),
  ampersand escaping (CR4-S1d), false-start anchor retry budget
  (CR4-T3), non-sequential step edge specificity (CR4-T4),
  plan_id propagation (CR5-T1), sequence_number monotonicity
  (CR5-T2), max_chars=3 boundary (CR5-T3), false-start anchor
  specificity (CR5-T4), word-boundary truncation (CR5-T5),
  invariant prompt constraints (CR6-M2), invariant XML
  sanitisation (CR6-M3), invariant truncation cap (CR6-M4),
  negative max_chars (CR6-M5), and no-space truncation (CR6-L8)
- 7 Robot Framework integration tests in robot/strategy_actor.robot
- Mock LLM provider in features/mocks/mock_strategy_llm.py

All nox stages pass: lint, typecheck, unit_tests (13789 scenarios),
integration_tests (1863 passed).
integration_tests (1863 passed, 2 pre-existing TDD failures unrelated
to this change).

ISSUES CLOSED: #828
 2026-04-17 09:00:15 +00:00
CleverAgents Build Agent bf41fa5669 Build: doom loops are detected and killed 2026-04-17 09:00:15 +00:00
CleverAgents Build Agent 00c844d149 Build: Refined some of the wording in the supervisors to get more reliable performance out of them. Made permissions stricter so we will get less circumvention of intended permissions 2026-04-17 09:00:15 +00:00
CleverAgents Build Agent ae521a96da Build: Improved merge, review, and implementor logic to have better and more clear priorities 2026-04-17 08:59:41 +00:00
HAL9000 4d22c1c534 docs(spec): add v3.8.0 Server Implementation milestone plan and update status table (#7701) 
Co-authored-by: CleverThis <hal9000@cleverthis.com>
Co-committed-by: CleverThis <hal9000@cleverthis.com>
 2026-04-17 08:59:41 +00:00
HAL9000 3c59cf049a docs: integrate docs-writer automation tracking workflows 
- document docs-writer responsibilities and automation tracking requirements\n- enforce automation tracking label validation and clean coverage regression tags\n\nISSUES CLOSED: #7616

# Conflicts:
#	CHANGELOG.md
#	docs/development/automation-tracking.md
#	docs/development/docs-writer.md
#	mkdocs.yml
 2026-04-17 08:56:36 +00:00
HAL9000 a007ef0644 docs(changelog): add plan action-arguments UNIQUE constraint fix (#4197) 
Documents the fix for sqlite3.IntegrityError when agents plan use is called on an action that already has arguments registered via action create.

ISSUES CLOSED: #6856
 2026-04-17 08:56:36 +00:00
CleverAgents Build Agent 9ac46a7c7d Build: improve grooming worker permissions, milestone enforcement, and PR merge throughput 
- Fix grooming-worker Forgejo permissions (deny → allow) to unblock direct API calls
- Route PR label fetching through forgejo-label-manager subagent
- Replace priority-alignment check with milestone enforcement (every issue must have a milestone)
- Add step 11: address non-code review remarks (labels, description, milestone) during grooming
- Clarify grooming-pool-supervisor stale threshold to explicit 24-hour window
- Refactor pr-merge-pool-supervisor main loop into explicit numbered steps
- Add triage strategy section emphasising parallel review checks and immediate worker dispatch
- Tighten merge criteria: explicit APPROVED state, no unresolved REQUEST_CHANGES on current head
- Dispatch workers for all PR processing, not only rebase operations
- Add rule to batch forgejo_list_pull_reviews calls instead of checking serially
 2026-04-17 08:56:36 +00:00
HAL9000 e87b757d65 docs(contributors): add HAL 9000 concurrency-fix contribution detail 
Add a Details entry for HAL 9000 describing the plan lifecycle
concurrency race-condition fix (#7989) — wiring LockService into
execute_plan/apply_plan with unique per-invocation owner identities.

ISSUES CLOSED: #7989
 2026-04-17 08:56:36 +00:00
HAL9000 5feca1abba fix(concurrency): fix lock owner identity to prevent re-entrant acquisition 
The original implementation used plan_id as the owner_id when acquiring
the advisory lock. Because LockService treats owner_id as the caller
identity and allows re-entrant acquisition for the same owner, concurrent
sessions attempting to lock the same plan would all present the same
owner_id and thus silently renew the lock instead of raising
LockConflictError.

This fix generates a unique UUID for each invocation as the owner_id,
ensuring that concurrent sessions present different owners and thus
trigger LockConflictError when attempting to acquire the same plan lock.
The lock is still acquired before the phase transition and released in
a finally block to ensure cleanup even on error.

ISSUES CLOSED: #8067
 2026-04-17 08:56:36 +00:00
HAL9000 b51358830e fix(concurrency): wire LockService into plan lifecycle — guard execute_plan and apply_plan 
LockService was implemented but never integrated into the plan execution
path, leaving execute_plan() and apply_plan() unprotected against
concurrent calls on the same plan_id (race condition, issue #7989).

Changes:
- container.py: add _build_lock_service() factory and register
  LockService as a Singleton provider; inject it into
  PlanLifecycleService via the DI container.
- plan_lifecycle_service.py: accept optional lock_service parameter in
  __init__; in execute_plan() and apply_plan() acquire a plan-level
  advisory lock before the critical section and release it in a finally
  block so the lock is always freed even when exceptions occur.

When lock_service is None (existing tests without DI wiring) the
behaviour is unchanged — locking is silently skipped for backward
compatibility.

Closes #7989
 2026-04-17 08:56:36 +00:00