AirCoding/AirPlan/docs/architecture/scope-escalation-v1.md

# 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
```