Initial commit: AirCoding V1.0.0 Alpha architecture baseline
Complete architecture document set with multi-model review remediation: - Frozen interface contracts, runtime semantics, DB schemas - Event/tool/error/provider registries - Scheduler and main agent state machines - C4 module/code views, solution architecture, baseline V1 - Multi-model review reports and joint assessment - Phase-gate remediation complete (P0/P1/P2/UX resolved) - Implementation plan with T-000A through T-045 - Reference folders kept as placeholders only
This commit is contained in:
AirCoding
283
AirPlan/docs/architecture/scope-escalation-v1.md
Normal file
283
AirPlan/docs/architecture/scope-escalation-v1.md
Normal file
@@ -0,0 +1,283 @@
|
||||
# AirCoding Scope Escalation Model V1
|
||||
|
||||
Date: 2026-05-27
|
||||
Status: Canonical scope escalation model for V1.0.0 Alpha skeleton
|
||||
|
||||
This document defines when agents may continue silently, when Scheduler must route to Architecture Designer, and when Main Agent/user confirmation is required.
|
||||
|
||||
## 1. Core Principle
|
||||
|
||||
Implementation-level changes that do not conflict with existing requirements, interfaces, architecture, or permissions may continue silently.
|
||||
|
||||
Architecture-level, product-level, safety-sensitive, or user-visible requirement changes require assessment and may require user confirmation depending on permission mode and impact.
|
||||
|
||||
## 2. Escalation Levels
|
||||
|
||||
```ts
|
||||
type ScopeImpactLevel =
|
||||
| "implementation"
|
||||
| "interface"
|
||||
| "architecture"
|
||||
| "product"
|
||||
| "permission"
|
||||
| "environment"
|
||||
| "policy"
|
||||
```
|
||||
|
||||
| Level | Meaning | Default action |
|
||||
|---|---|---|
|
||||
| `implementation` | internal code details within accepted scope | silent continue |
|
||||
| `interface` | public API/schema/module boundary changes | Architecture Designer assessment |
|
||||
| `architecture` | component responsibility/data flow/runtime model changes | Architecture Designer + likely user-visible summary |
|
||||
| `product` | changes user-facing goal, behavior, UX, or acceptance criteria | Main Agent/user confirmation |
|
||||
| `permission` | action exceeds current permission grant | PermissionEngine/Main Agent |
|
||||
| `environment` | dependency/toolchain/platform blocker | Doctor/Debugger, then Main Agent if unresolved |
|
||||
| `policy` | safety/security/legal/project policy issue | block until explicit decision or refuse |
|
||||
|
||||
## 3. Silent Continue Criteria
|
||||
|
||||
An agent may continue without escalation when all are true:
|
||||
|
||||
1. Change is inside TaskSpec scope/write area.
|
||||
2. Acceptance criteria remain unchanged.
|
||||
3. Public interfaces and architecture decisions remain unchanged.
|
||||
4. No denied path, credential, system-sensitive, or unapproved network access is needed.
|
||||
5. Verification plan remains valid.
|
||||
6. Change does not contradict project rules or latest user instructions.
|
||||
7. Risk is low or normal for the task type.
|
||||
|
||||
Examples:
|
||||
|
||||
```text
|
||||
rename local variable
|
||||
adjust private helper implementation
|
||||
fix compile error without API change
|
||||
add missing test for accepted behavior
|
||||
change internal algorithm with same contract
|
||||
```
|
||||
|
||||
## 4. Architecture Designer Assessment Criteria
|
||||
|
||||
Route to Architecture Designer when any are true:
|
||||
|
||||
1. Public function/class/module interface must change.
|
||||
2. DB schema or persisted data shape must change.
|
||||
3. IPC/event/tool contract must change.
|
||||
4. Dependency graph or component responsibility changes.
|
||||
5. Task requires new subsystem/capability not in plan.
|
||||
6. Multiple tasks conflict semantically, not just textually.
|
||||
7. A user requirement change may affect architecture.
|
||||
8. Repeated failures indicate the plan itself is wrong.
|
||||
|
||||
Architecture Designer outputs `architecture.impact.completed`:
|
||||
|
||||
```ts
|
||||
interface ArchitectureImpactCompletedPayload {
|
||||
assessment_id: string
|
||||
requirement_change_id?: string
|
||||
impact_level: "implementation" | "interface" | "architecture" | "product"
|
||||
decision: "silent_continue" | "requires_user_confirmation" | "requires_replan" | "reject_or_escalate"
|
||||
summary: string
|
||||
affected_task_ids?: string[]
|
||||
evidence_refs?: EvidenceLink[]
|
||||
}
|
||||
```
|
||||
|
||||
## 5. User Confirmation Criteria
|
||||
|
||||
Main Agent asks the user when any are true:
|
||||
|
||||
1. Product behavior or acceptance criteria changes.
|
||||
2. Architecture Designer marks `requires_user_confirmation`.
|
||||
3. Low-permission mode requires approval for the planned action.
|
||||
4. Credentials or system-sensitive operations are involved.
|
||||
5. Migration or destructive/shared-state operation is involved.
|
||||
6. Safety/policy boundary requires explicit authorization.
|
||||
7. Failure cannot be resolved without user preference or external input.
|
||||
|
||||
High-permission mode may auto-execute many actions after visible `announce_then_run`, but cannot bypass:
|
||||
|
||||
```text
|
||||
credentials
|
||||
system_sensitive
|
||||
migration confirmation
|
||||
policy refusal boundary
|
||||
destructive/shared-state actions requiring explicit confirmation
|
||||
```
|
||||
|
||||
## 6. Environment Escalation
|
||||
|
||||
Environment/toolchain issues follow:
|
||||
|
||||
```text
|
||||
worker detects issue
|
||||
→ Doctor/Debugger evidence
|
||||
→ if fix is allowlisted and permission mode allows: announce_then_run or ask
|
||||
→ if fix fails or unsupported platform: Main Agent blocker report
|
||||
→ if architecture assumptions invalid: Architecture Designer assessment
|
||||
```
|
||||
|
||||
Examples requiring environment escalation:
|
||||
|
||||
```text
|
||||
missing compiler/toolchain
|
||||
kernel feature unavailable
|
||||
package manager unavailable
|
||||
insufficient disk space
|
||||
X/display backend missing for GUI evidence
|
||||
```
|
||||
|
||||
## 7. Permission Escalation
|
||||
|
||||
PermissionEngine returns an action plus a grant scope:
|
||||
|
||||
```text
|
||||
action: allow | deny | ask_user | block | refuse | announce_then_run
|
||||
grant_scope: none | once | session | project | global
|
||||
```
|
||||
|
||||
Routes:
|
||||
|
||||
| Action | Route |
|
||||
|---|---|
|
||||
| `allow` | execute according to `grant_scope`; create backup first when `backup_required` is true |
|
||||
| `announce_then_run` | visible notice, auto-execute if not interrupted; grant is bounded by `grant_scope` |
|
||||
| `ask_user` | Main Agent/UI prompt |
|
||||
| `deny` | do not execute this request; caller may choose another safe path |
|
||||
| `block` | task.blocked |
|
||||
| `refuse` | policy_error and cancellation/blocker |
|
||||
|
||||
## 8. Requirement Change Handling
|
||||
|
||||
When the user changes requirements during execution:
|
||||
|
||||
```text
|
||||
Main Agent records requirement.changed
|
||||
Scheduler pauses affected dispatch/merge decisions
|
||||
Architecture Designer assesses if needed
|
||||
Scheduler cancels, interrupts, replans, or continues affected tasks
|
||||
Main Agent reports visible impact summary
|
||||
```
|
||||
|
||||
Classification:
|
||||
|
||||
| Change | Handling |
|
||||
|---|---|
|
||||
| clarification only | update context; continue |
|
||||
| implementation detail | Scheduler updates pending tasks; running tasks may continue if unaffected |
|
||||
| scope change | interrupt affected tasks and replan |
|
||||
| architecture change | Architecture Designer assessment |
|
||||
| cancellation | cancel affected tasks and preserve workspaces/artifacts |
|
||||
|
||||
## 9. Worker Self-Escalation Contract
|
||||
|
||||
Workers return `blocked` instead of improvising when they detect:
|
||||
|
||||
```text
|
||||
architecture/interface mismatch
|
||||
permission denial
|
||||
missing product decision
|
||||
unsupported environment condition
|
||||
unsafe requested behavior
|
||||
verification cannot be run and acceptance depends on it
|
||||
TaskSpec scope insufficient for necessary change
|
||||
```
|
||||
|
||||
WorkerResult blocker fields:
|
||||
|
||||
```ts
|
||||
interface BlockerReport {
|
||||
impact_level: ScopeImpactLevel
|
||||
reason: string
|
||||
required_decision: string
|
||||
options?: Array<{ label: string; tradeoff: string }>
|
||||
evidence_refs?: EvidenceLink[]
|
||||
suggested_default?: string
|
||||
}
|
||||
```
|
||||
|
||||
## 10. Scheduler Escalation Decision
|
||||
|
||||
Scheduler maps task/agent/tool events to one of:
|
||||
|
||||
```text
|
||||
continue
|
||||
retry
|
||||
retry_serial
|
||||
debug
|
||||
ask_permission
|
||||
architecture_assessment
|
||||
ask_user
|
||||
cancel
|
||||
refuse
|
||||
```
|
||||
|
||||
Decision inputs:
|
||||
|
||||
```text
|
||||
error kind
|
||||
failure signature repetition
|
||||
TaskSpec scope
|
||||
permission result
|
||||
architecture impact
|
||||
verification evidence
|
||||
resource/environment state
|
||||
user permission mode
|
||||
```
|
||||
|
||||
## 11. User-Facing Reports
|
||||
|
||||
Escalation reports should be short and actionable:
|
||||
|
||||
```text
|
||||
What changed or failed
|
||||
Why AirCoding cannot safely continue silently
|
||||
Evidence summary
|
||||
Recommended default action
|
||||
Alternatives if meaningful
|
||||
```
|
||||
|
||||
Do not show implementation noise when the decision is product-level. Do show precise evidence when the decision affects architecture, data loss, security, or environment setup.
|
||||
|
||||
## 12. Examples
|
||||
|
||||
### Silent implementation fix
|
||||
|
||||
A C++ build fails because a private helper has a mismatched parameter type. Executor edits the helper and reruns build/tests. No escalation.
|
||||
|
||||
### Interface-level escalation
|
||||
|
||||
A task discovers the accepted API cannot support required streaming. Executor returns blocked. Architecture Designer assesses interface change and updates plan/ADR before Scheduler continues.
|
||||
|
||||
### Product-level escalation
|
||||
|
||||
User asked for local-only storage, but implementation requires cloud sync to meet a new requirement. Main Agent asks user; no silent change.
|
||||
|
||||
### Environment escalation
|
||||
|
||||
Build requires a missing compiler. Doctor can install it. In high-permission mode this may be announced and run if allowlisted; credentials/system-sensitive steps still ask.
|
||||
|
||||
### Policy escalation
|
||||
|
||||
Requested behavior would steal credentials or hide persistence. AirCoding refuses; no architecture workaround.
|
||||
|
||||
## 13. V1.0.0 Alpha Cut Line
|
||||
|
||||
V1.0.0 Alpha skeleton must implement:
|
||||
|
||||
1. ScopeImpactLevel contract.
|
||||
2. Silent continue checks for workers.
|
||||
3. Worker blocked report schema.
|
||||
4. Architecture impact event route.
|
||||
5. PermissionEngine route integration.
|
||||
6. Scheduler escalation decision table.
|
||||
7. Main Agent blocker/confirmation presentation.
|
||||
|
||||
Post-MVP:
|
||||
|
||||
```text
|
||||
learned escalation classifier
|
||||
risk scoring by code ownership/history
|
||||
interactive impact visualization
|
||||
automated ADR draft generation from repeated escalations
|
||||
```
|
||||
Reference in New Issue
Block a user