- Add detailed v3.8.0 milestone plan with 15 deliverables, architectural constraints, and definition of done
- Update milestone status table with current issue counts (as of 2026-04-13)
- Add v3.9.0 Documentation & Maintenance to status table
- Update plan coverage from v3.7.0 to v3.8.0
Closes#8195 (supersedes the navigation-only approach with full section)
[AUTO-ARCH-3]
- Create docs/guides/troubleshooting.md: comprehensive troubleshooting
guide covering installation, LLM provider, database, plan execution,
TUI, and test suite issues with step-by-step remediation
- Create docs/guides/faq.md: practical FAQ covering setup, actors,
tools/skills, plans, testing, and contributing
- Create docs/guides/index.md: guides landing page with navigation table
- Expand docs/api/config.md: add complete CLEVERAGENTS_* env var
reference, config file TOML format, actor YAML format, and action
YAML format
- Update mkdocs.yml: add Guides section to site navigation
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.
Three implementation contracts clarified in response to security/correctness
bugs surfaced by the bug hunt pool:
1. Path containment: Sandbox path validation MUST use Path.is_relative_to()
not string prefix comparison. String prefix allows /tmp/sandboxmalicious
to pass a /tmp/sandbox root check. Canonical implementation provided.
2. Datetime handling: All stored ISO timestamp comparisons MUST parse back
to timezone-aware datetime objects before comparing. String comparison
of ISO timestamps is incorrect when timezone offsets differ in format.
Canonical parse_utc_ts() pattern provided.
3. Plugin protocol validation: Protocol compliance MUST be checked
structurally via issubclass() — never by instantiating the plugin class.
Instantiation runs __init__ side effects before the plugin is approved.
These are minor clarifications (implementation contracts, not architectural
changes) added to the existing Security and Extensibility sections.
Updated CHANGELOG.md with entry for this documentation change.
Refs: BUG-HUNT issues #7336 (path traversal), #7341 (datetime comparison),
#7331 (plugin instantiation)
ISSUES CLOSED: #7680
Created comprehensive formal release notes for the v3.0.0 (Minimal Local
Source-Code Workflow) and v3.1.0 (Actor Compiler + Full LLM Integration)
milestones, along with a release notes index.
New files:
- docs/release-notes/index.md: Index of all release notes with release
series overview and guidance on how to read release notes
- docs/release-notes/v3.0.0.md: Full release notes for v3.0.0 covering
plan lifecycle (Action→Strategize→Execute→Apply), git worktree sandbox,
SQLite persistence, actor-based LLM path, ChangeSet tracking, Pydantic
v2 domain models, CLI commands, and ADR references
- docs/release-notes/v3.1.0.md: Full release notes for v3.1.0 covering
Actor YAML→LangGraph compilation, MCP adapter, validation runner,
multi-file generation, skill registry, Agent Skills standard, LSP
integration, breaking changes, and migration guide
Updated CHANGELOG.md:
- Expanded [3.0.0] section with detailed bullet points for each major
feature, ADR references, and a link to the full release notes
- Expanded [3.1.0] section with detailed bullet points for each major
feature, ADR references, breaking changes, and a link to the full
release notes
- Update validation attach synopsis from [<ARGS>...] to [--<key> <value>]...
- Update arguments description to document named option format
- Update inline references to use named option format
- Update management table to reflect named option format
- Add deleted_at field to project delete JSON and YAML output examples
These changes document the behavior implemented in PR #3837 (validation attach
named options) and PR #6639 (project delete deleted_at field).
ISSUES CLOSED: #7533
Document four architecture decisions that resolve violations detected by
the automated guard scan:
- ADR-049: Introduce SandboxGateway protocol in the domain layer to
eliminate resource handler imports from infrastructure (issue #8058)
- ADR-050: Canonicalize plan identifiers to ULID strings across all
application-layer services, removing integer surrogate ID leakage
(issue #8059)
- ADR-051: Decompose PlanLifecycleService (2,649 lines) into eight
focused modules each ≤500 lines, compliant with CONTRIBUTING.md
(issue #8061)
- ADR-052: Replace placeholder assert-True BDD steps with real
lifecycle assertions that verify observable behavior (issue #8062)
ISSUES CLOSED: #8058, #8059, #8061, #8062
- Add empty-run guard section to ApplyValidationSummary explaining that
all_required_passed now returns False when is_empty is True
- Add required_total property to the properties list
- Add is_empty column to ValidationSummary model table
- Include behaviour table showing all three gate outcomes
- Document why the guard matters (silent bypass of apply gate)
Closes#7508 documentation gap.
The spec described invariant reconciliation as happening 'during Strategize'
only. The implementation (PR #5614) runs reconciliation at all three phase
transitions: Strategize, Execute, and Apply.
Added §Reconciliation Failure Behavior documenting:
- Reconciliation runs at start_strategize(), execute_plan(), apply_plan()
- ReconciliationBlockedError is raised when reconciliation fails
- INVARIANT_VIOLATED event is emitted on the event bus
- Resolution path: plan correct + retry
- Post-correction reconciliation via CORRECTION_APPLIED event subscription
- Built-in actor: builtin/invariant-reconciliation
Closes#5942
PR #6571 (merged) updated agents plan tree to display full 26-character
ULIDs for all child plan IDs instead of truncated 8-char prefixes. This
enables copy-paste usability for plan correct and plan tree commands.
Updated the spec to:
- Show full 26-char ULIDs in tree body for subplan_spawn entries
- Show full 26-char ULIDs in Child Plans table
- Show full 26-char ULIDs in JSON/YAML output plan_id fields
- Add a note documenting the full ULID display behavior and per-type
ordinal labels in the Decision IDs panel
Closes#7898
The implementation (PR #6639, merged 2026-04-10) produces a simpler
output for agents project delete than what the spec described:
{"deleted": "local/docs", "success": true, "deleted_at": "..."}
The spec previously showed a rich deletion_summary/index_cleanup/backups
structure that does not match the actual implementation. Updated to
reflect the actual output including the deleted_at timestamp field.
Closes#7872
- Change validation attach synopsis from positional [<ARGS>...] to named
option [--<key> <value>]... format, matching PR #3837 implementation
(Typer Context with allow_extra_args=True; positional key=value rejected)
- Update argument description to document hyphen-to-underscore normalization
- Update all inline references in Validation Attachment Scopes section and
Validation Abstraction section to use named option format
- Add deleted_at timestamp field to project delete JSON/YAML output examples,
matching PR #6639 implementation
Closes#7533
Two spec gaps were causing UAT failures (#7461, #7462):
1. agents invariant add: Add --non-overridable flag to CLI synopsis and
argument list. The flag was documented in the conceptual section
(Layer 3: Invariant Enforcement) but absent from the CLI command
definition, causing implementers to omit it entirely.
2. agents invariant list: Clarify that --effective is valid with both
--plan and --action (not only --plan). The synopsis already showed
--effective without restriction, but the argument description said
'Only with --plan', causing the implementation to reject
--effective --action. Add example output for the --action --effective
combination.
3. InvariantEnforcer code snippet: Fix precedence list to include
'action' tier (plan > action > project > global), matching the
four-tier precedence defined in the Invariant glossary entry.
Fixes: #7461, #7462 (spec gaps — implementation work tracked separately)
UAT findings #7461 and #7462 identified two spec-implementation gaps in
the invariant system:
1. Missing --non-overridable CLI flag (#7461):
The spec defines 'agents invariant add --global --non-overridable'
but the CLI raises 'No such option: --non-overridable'. System
administrators cannot create non-overridable global safety constraints.
2. Action-scope omitted from --effective output (#7462):
The spec defines four-tier precedence (plan > action > project > global)
but InvariantService.get_effective_invariants() only merges plan/project/
global, omitting action scope entirely. The --effective output also
ignores non_overridable semantics.
Added 'CLI completeness requirements for invariants' section clarifying:
- --non-overridable flag MUST be implemented (global scope only)
- Action-scope MUST be included in --effective output
- non_overridable semantics MUST be correctly applied in --effective
Refs: UAT #7461, UAT #7462
Bug #7443 found that CleanupService._get_sandbox_dirs() permanently caches
the list of sandbox directories from the first scan. Since the cleanup service
is a long-running singleton, sandboxes created after the first scan are never
discovered and never cleaned up.
Added 'Sandbox cleanup re-discovery contract' to the Sandbox Security
Invariants section clarifying that:
- The cleanup service MUST re-discover sandbox directories on each scan/purge
- It MUST NOT cache the directory list across invocations
- Sandbox directories are created dynamically during plan execution
- Permanent caching causes stale sandbox accumulation
Refs: bug #7443 (CleanupService stale sandbox directory cache)
- docs/reference/plan_cli.md: add Full ULID Display section to agents plan tree
documenting the change from truncated 8-char IDs to full 26-char ULIDs (PR #6571),
including the new Decision IDs for correction section and updated examples showing
direct use of tree output IDs in follow-up commands
- CHANGELOG.md: add Fixed entry for agents plan tree full ULID display (PR #6571)
ISSUES CLOSED: #7674
Two spec gaps identified from UAT and bug hunt findings:
1. fail_fast cancel semantics (UAT #7394):
The spec defined fail_fast as a SubplanConfig option but did not specify
what state unstarted subplans should transition to when fail_fast triggers.
UAT found that unstarted subplans end up in 'complete' state instead of
'cancelled', which is a spec violation.
Clarification: When fail_fast=true and a parallel subplan errors, all
queued (not yet started) subplans MUST transition to 'cancelled' state.
'cancelled' is semantically distinct from 'complete' — it means the
subplan was never started due to a sibling failure.
2. A2A facade idempotency contract (bug #7389):
The spec described A2A extension methods but did not specify that they
must be idempotent. Bug found that _handle_plan_apply() raises
InvalidPhaseTransitionError when called on an already-applied plan,
breaking idempotency.
Clarification: All _cleveragents/plan/* methods MUST be idempotent.
Before invoking the underlying service, check the current plan phase.
If already at or past the target phase, return current state without
re-invoking. Raising InvalidPhaseTransitionError to the A2A caller
is a spec violation.
Refs: UAT #7394, bug #7389
Bug #7373 found that PermissionService.is_local_mode() reads the
CLEVERAGENTS_SERVER_MODE environment variable on every permission check
call. This creates a TOCTOU vulnerability: if any code path can modify
os.environ during a session, the security mode can be changed mid-session,
bypassing permission enforcement.
Added a 'Security mode initialization contract' to the Security section
clarifying that:
- Deployment mode (local vs. server) MUST be determined once at service
initialization time and cached
- Never re-read from environment variables on each permission check
- PermissionService and any other mode-gating service must cache at init
Refs: bug #7373 (PermissionService.is_local_mode() TOCTOU vulnerability)
The spec's 'Critical Design Decision' stated 'no on-demand indexing during
agent execution', but PR #4219 introduced context_tier_hydrator.py which
does exactly that — populating the in-memory ContextTierService from linked
project resources at the start of each plan execution.
This is a spec-implementation divergence that needed clarification:
- Context tier hydration is a lightweight file-read bridge (not full ACMS
indexing). It populates the HOT tier with raw file content so the LLM
has file context during plan execution.
- Full ACMS indexing (UKO ontology graphs, embeddings, persistent index)
is what the 'no on-demand' principle applies to.
- When the full ACMS pipeline is implemented with persistent index state,
hydration will be replaced by reading from the persisted index.
Added a note block under the Critical Design Decision explaining the
distinction, the hydration algorithm, and the relationship to the principle.
Refs: issue #7365 (spec update proposal from spec-updater agent),
PR #4219 (fix(acms): wire ACMS indexing pipeline into CLI)
Add spec coverage for four new architectural features:
1. Actor node model_tier field: Optional per-node model tier override (cheap/default/frontier)
in graph route nodes. Tier-to-model mapping via new model.tiers.* config keys.
Enables cost-optimised actor graphs without hardcoding model names.
2. Autonomous shell blocking: Safety Profile integration with ShellSafetyService.
When allow_unsafe_tools=false and profile is headless (ci/full-auto), CRITICAL+HIGH
shell patterns are hard-blocked rather than advisory. TUI remains advisory-only.
3. In-actor conversation history compaction: LangGraph actor runner hook that monitors
accumulated message history and summarises old turns when threshold exceeded.
Distinct from ACMS (which handles retrieval); this handles within-session accumulation.
New actor.compaction.* config keys.
4. Uncertainty band LLM escalation: Optional two-stage AutonomyController augmentation.
Stage 1 heuristic runs always (zero LLM cost). Stage 2 cheap LLM evaluator activates
only when score falls within uncertainty band around threshold. Result caching and
circuit breaker included. New escalation.classifier.* config keys.
Closes: #6765, #6763, #6761, #6760
ISSUES CLOSED: #6765, #6763, #6761, #6760
HAL9000
Repo Isolator
CleverAgents Bot
HAL9000