UAT: `docs/reference/automation_profiles.md` resolution precedence omits "action" level — inconsistent with ADR-017 and code #4867

New issue

Open

opened 2026-04-08 20:10:40 +00:00 by HAL9000 · 0 comments

HAL9000 commented

2026-04-08 20:10:40 +00:00

Owner

Summary

The reference documentation for automation profiles describes a 4-level resolution precedence that omits the "action" level, making it inconsistent with both ADR-017 and the actual code implementation.

What Was Tested

Code-level analysis comparing docs/reference/automation_profiles.md, docs/adr/ADR-017-automation-profiles.md, and src/cleveragents/application/services/automation_profile_service.py.

Expected Behavior (from ADR-017 and code)

ADR-017 defines the resolution precedence as:

plan (--automation-profile flag) > action (automation_profile field) > project (core.automation-profile) > global (core.automation-profile)

Code (AutomationProfileService.resolve_profile()) implements:

resolved_name = (
    plan_profile
    or action_profile      # <-- action level IS present in code
    or project_profile
    or self.effective_global_default
)

The action level is a distinct tier that allows an action template to specify a default profile for plans created from it.

Actual Behavior (from reference docs)

docs/reference/automation_profiles.md describes:

1. Plan-level override — A profile specified directly on the plan.
2. Project-level setting — The default profile configured for the project.
3. Organization-level default — The organization's default profile.
4. System default — Falls back to the `review` built-in profile.

The "action" level is completely absent from the reference docs. Additionally:

The reference docs use "Organization-level default" which doesn't appear in ADR-017 or the code (the code uses "global" not "organization")
The reference docs say the system default is review, but ADR-017 says supervised (see also issue #4853)

Impact

Developers reading the reference docs will not know that action templates can specify a default automation profile
The action_profile parameter of AutomationProfileService.resolve_profile() is undocumented in the reference material
The discrepancy between "organization-level" (docs) and "global" (ADR-017/code) creates confusion about the configuration key

Code Location

docs/reference/automation_profiles.md — "Resolution Precedence" section
src/cleveragents/application/services/automation_profile_service.py — resolve_profile() method
docs/adr/ADR-017-automation-profiles.md — "Profile Resolution" section

Definition of Done

docs/reference/automation_profiles.md "Resolution Precedence" section updated to include the "action" level: plan > action > project > global
Terminology aligned between reference docs and ADR-017 ("global" vs "organization-level")
System default value reconciled (see issue #4853)
The action_profile parameter is documented with an example showing action-level profile inheritance

Automated by CleverAgents Bot
Supervisor: UAT Testing | Agent: uat-tester

## Summary The reference documentation for automation profiles describes a 4-level resolution precedence that omits the "action" level, making it inconsistent with both ADR-017 and the actual code implementation. ## What Was Tested Code-level analysis comparing `docs/reference/automation_profiles.md`, `docs/adr/ADR-017-automation-profiles.md`, and `src/cleveragents/application/services/automation_profile_service.py`. ## Expected Behavior (from ADR-017 and code) **ADR-017** defines the resolution precedence as: ``` plan (--automation-profile flag) > action (automation_profile field) > project (core.automation-profile) > global (core.automation-profile) ``` **Code** (`AutomationProfileService.resolve_profile()`) implements: ```python resolved_name = ( plan_profile or action_profile # <-- action level IS present in code or project_profile or self.effective_global_default ) ``` The action level is a distinct tier that allows an action template to specify a default profile for plans created from it. ## Actual Behavior (from reference docs) `docs/reference/automation_profiles.md` describes: ``` 1. Plan-level override — A profile specified directly on the plan. 2. Project-level setting — The default profile configured for the project. 3. Organization-level default — The organization's default profile. 4. System default — Falls back to the `review` built-in profile. ``` The "action" level is **completely absent** from the reference docs. Additionally: - The reference docs use "Organization-level default" which doesn't appear in ADR-017 or the code (the code uses "global" not "organization") - The reference docs say the system default is `review`, but ADR-017 says `supervised` (see also issue #4853) ## Impact - Developers reading the reference docs will not know that action templates can specify a default automation profile - The `action_profile` parameter of `AutomationProfileService.resolve_profile()` is undocumented in the reference material - The discrepancy between "organization-level" (docs) and "global" (ADR-017/code) creates confusion about the configuration key ## Code Location - `docs/reference/automation_profiles.md` — "Resolution Precedence" section - `src/cleveragents/application/services/automation_profile_service.py` — `resolve_profile()` method - `docs/adr/ADR-017-automation-profiles.md` — "Profile Resolution" section ## Definition of Done - [ ] `docs/reference/automation_profiles.md` "Resolution Precedence" section updated to include the "action" level: `plan > action > project > global` - [ ] Terminology aligned between reference docs and ADR-017 ("global" vs "organization-level") - [ ] System default value reconciled (see issue #4853) - [ ] The `action_profile` parameter is documented with an example showing action-level profile inheritance --- **Automated by CleverAgents Bot** Supervisor: UAT Testing | Agent: uat-tester

HAL9000 referenced this issue

2026-04-08 20:11:32 +00:00

[Automated] CleverAgents Build Session - 2026-04-08 #4799

HAL9000 referenced this issue

2026-04-08 20:16:04 +00:00

[Automated] CleverAgents Build Session - 2026-04-08 #4799

HAL9000 added this to the v3.5.0 milestone

2026-04-08 20:18:56 +00:00

HAL9000 referenced this issue

2026-04-08 20:19:20 +00:00

[Automated] CleverAgents Build Session - 2026-04-08 #4799

HAL9000 referenced this issue